skill-manager

Skill Manager

Manage the full lifecycle of Skills: scan, check for updates, upgrade, delete, and manage the experience layer.

Core Features

1. Scan and Audit: Scan the Skills directory and parse the frontmatter metadata of all SKILL.md files
2. Version Check: Concurrently query GitHub (via git ls-remote) to compare local and remote hashes
3. Status Report: Generate a status report identifying outdated/current/unmanaged/error
4. Update Workflow: Guide the Agent to perform a Skill upgrade
5. Inventory Management: List and delete Skills
6. Experience Layer Management: The promote/pull commands synchronize experience between layers

Startup Flow (Important)

Each time skill-manager is invoked, the following flow must first be executed to determine the Skills directory:

Step 1: Check configuration

Run python scripts/config.py get to check whether the Skills directory has been configured.

Step 2: Handle based on configuration status

Case A - Configured:

1. Confirm with the user: "The Skills in <skills_dir> will be managed, confirm to continue?"
2. User confirms → continue executing the operation
3. User declines → ask for a new path, run python scripts/config.py set <new_path>

Case B - Not configured:

1. Run python scripts/config.py detect to auto-detect
2. Detection succeeds → confirm the detected path with the user, and continue after confirmation
3. Detection fails → ask the user for the Skills directory path, then run python scripts/config.py set <path>

Example Dialogue

Agent: 检查 skill-manager 配置...
Agent: 已配置 Skills 目录: /Users/xxx/.claude/skills
Agent: 将管理该目录中的 Skills，确认继续？
User: 确认
Agent: [执行用户请求的操作]

Agent: 检查 skill-manager 配置...
Agent: 未找到配置，正在自动检测...
Agent: 检测到 Skills 目录: /Users/xxx/.claude/skills
Agent: 是否使用该目录？
User: 是
Agent: 已保存配置。[执行用户请求的操作]

Note: Do not explore the current working directory to find Skills. The Skills directory is the location where the user specifically stores Skills and is unrelated to the current project.

---

Use Cases

Check for Updates

Trigger Methods:

• /skill-manager check
• "Check whether my Skills have updates"
• "Scan Skills for updates"

Workflow:

1. The Agent runs the scripts/scan_and_check.py <skills_dir>
2. script to concurrently check all Skills with source_url Skills
3. Output a status report in JSON format
4. The Agent presents the results to the user

Example Output:

Skills 状态摘要
========================================
总计: 12 个 Skills
  - 最新: 8
  - 需更新: 2
  - 非托管: 1
  - 错误: 1

需要更新的 Skills:
  - yt-dlp: New commits available
    本地: abc123...
    远程: def456...

List Skills

Trigger Methods:

• /skill-manager list
• "List my Skills"
• "Show all Skills"

Workflow:

1. The Agent runs scripts/list_skills.py <skills_dir>
2. Output a Skills list in table or JSON format

Example Output:

Name                   | Type     | Ver      | Description
-----------------------|----------|----------|------------------------------------------
md-to-pptx             | Standard | 1.0.0    | Markdown 转 PowerPoint 工具...
n8n-workflow-patterns  | Standard | 1.0.0    | n8n 工作流模式专家...
yt-dlp                 | GitHub   | 0.1.0    | YouTube 视频下载工具封装...
-----------------------|----------|----------|------------------------------------------
Total: 12 skills

Update Skill

Trigger Methods:

• "Update [Skill name]" (after checking for updates)
• /skill-manager update <skill_name>

Workflow:

1. The Agent fetches the new README from the remote repository
2. Compare the old and new READMEs to identify changes (new features, deprecated parameters, etc.)
3. Rewrite SKILL.md to reflect the new features
4. Update the source_hash field
5. Optional: update wrapper.py
6. Run skill-evolution 's align_all.py to restore user experience

Delete Skill

Trigger method:

• /skill-manager delete <skill_name>
• "Delete Skill: <skill_name>"

Workflow:

1. Agent runs scripts/delete_skill.py <skill_name> <skills_dir>
2. Script displays Skill information and requests confirmation
3. Optional: Back up to .skill-backup directory
4. Execute deletion

Experience layer management

View experience status

Trigger method:

• /skill-manager evo-status <skill_name>
• "View xxx's experience status"

Workflow:

python scripts/evo_manager.py evo-status <skill_name> [--project <path>]

Example output:

Skill: n8n-code-javascript
Project: /Users/xxx/my-project

Layers:
  [✗] Upstream
      Path: ~/.claude/skills-repo/skills/n8n-code-javascript/evolution.json
  [✓] Global
      Path: ~/.claude/evolutions/n8n-code-javascript/evolution.json
      Items: 5 total
        - preferences: 2
        - fixes: 2
        - contexts: 1
  [✓] Project
      Path: /Users/xxx/my-project/.claude/evolutions/n8n-code-javascript.json
      Items: 3 total
        - preferences: 1
        - fixes: 2

Merged Total: 8 items

Promote experience to global layer

Trigger method:

• /skill-manager promote <skill_name>
• "Promote this project's experience to global"

Workflow:

python scripts/evo_manager.py promote <skill_name> [--project <path>] [--fields f1,f2]

Copy the current project's experience to the global layer for sharing across all projects.

Pull experience from global layer

Trigger method:

• /skill-manager pull <skill_name>
• "Pull global experience into this project"

Workflow:

python scripts/evo_manager.py pull <skill_name> [--project <path>]

Copy the global layer's experience to the current project, used for initializing new projects.

Sync all experience statuses

Trigger method:

• /skill-manager sync-evolutions
• "View the experience status of all Skills"

Workflow:

python scripts/evo_manager.py sync [--skills-dir <path>] [--project <path>]

Example output:

============================================================
Skills Evolution Status Summary
============================================================
Skills Directory: ~/.claude/skills-repo/skills
Project Path: /Users/xxx/my-project
Total Skills: 14

Summary:
  - Has upstream evolution: 2
  - Has global evolution: 5
  - Has project evolution: 3
  - No evolution data: 8

Skills Detail:
------------------------------------------------------------
Name                            Up   Glb   Prj  Total
------------------------------------------------------------
md-to-pptx                       -     ✓     -      3
n8n-code-javascript              -     ✓     ✓      8
n8n-code-python                  -     -     -      0
...
------------------------------------------------------------

Script description

Script	Function	Parameter
config.py	Configuration management	get|set <path>|detect|clear
scan_and_check.py	Scan and check for updates	<skills_dir> [--json|--summary|--table]
list_skills.py	List all Skills	<skills_dir> [--json] [--verbose]
delete_skill.py	Delete Skill	<skill_name> <skills_dir> [--backup] [--force]
evo_manager.py	Experience layer management	<command> <skill_name> [options]

evo_manager.py commands

Command	Function
evo-status <skill>	View experience distribution status
promote <skill>	Project experience → Global layer
pull <skill>	Global experience → Project layer
sync	View experience status of all skills

Metadata dependencies

This manager depends on the following metadata fields:

Field	Purpose
source_url	Remote repository URL (used to check for updates)
source_hash	Locally recorded commit hash
version	Semantic version number
evolution_enabled	Whether experience evolution is enabled

Compatibility: Also supports the old-format github_url and github_hash fields.

Status description

Status	Meaning
current	Local hash is the same as remote, no update needed
outdated	Remote has new commits
unmanaged	Not configured source_url, unable to check for updates
error	Unable to access remote repository
unknown	No hash recorded locally

Best practices

1. Regular checks: It is recommended to run /skill-manager check
2. Backup before deletion: Before deleting an important Skill, use the --backup option
3. Align after updating: After updating a Skill, run skill-evolution 's align_all.py to restore experience
4. Version control: Use Git to manage the Skills directory for easy rollback
5. Experience management:
   • Run when starting a new project pull to obtain global experience
   • Run at the end of a project promote to promote valuable experience
   • Run periodically sync view the experience distribution

Collaboration with other Skills

• skill-factory: Created Skills automatically include the metadata required for lifecycle management
• skill-evolution: call after update align_all.py restore user experience; share layered_merge.py
• skill-creator: follow the same metadata specification