Skill Manager

Skill Manager (SM)

Repository Structure & Flattened Design (扁平化設計)

• custom/: Your internal/original skills.
• external/: Community skills downloaded for inspection and reference.

Flattened vs. Conditional Nesting (扁平化與條件式嵌套)

To balance discoverability and organization:

• Default (Flattened): Every skill folder SHOULD be a direct child of its domain folder for default detection by npx skills add <directory>.
• Exception (Conditional Nesting): If a domain directory contains more than 10 skills, you MAY create one level of sub-directories (categories) to avoid clutter.
  • Note: When nesting is used, users must use npx skills add <path> --full-depth to find all skills.
• Sync Requirement: Whenever a skill's location changes, you MUST immediately update the corresponding link in SKILLS_LIST.md.

Taxonomy Alignment (目錄架構對齊)

To prevent fragmentation (e.g., mixing search/ and fetch/ for similar tools), you MUST map external skills to our existing local domains/categories:

• Local Domains: basic/, develop/, obsidian/, video-design/, writing/.
• Ignore Provider Names: If an external repo uses research/firecrawl, but we use basic/, move it to external/basic/firecrawl-search/.
• Consistency over Originality: Always prioritize our folder structure over the external repository's original layout.

Utility Skills

Leverage these skills to maintain the repository:

• /find-skills: Discover existing skills in the ecosystem to avoid duplication.
• /skills-validator: Validate skills in custom/ or external/ against the agentskills.io spec.
• /skills-creator: Follow guided workflows to create new skills with proper structure.

Refactoring & Efficiency

• Progressive Disclosure: Use the /reference pattern to keep skills efficient. Read references/REFACTORING.md for the refactoring SOP.

Core Commands

• Single-Skill Update (default for the "Remote Install" SOP step): When only one skill changed, run npx skills add <user>/<repo>/<custom|external>/<domain>/<skill-name> for that skill alone. Do NOT run ./setup.sh for a single-skill change — it re-registers every skill in the repo, which is out of scope and can touch unrelated installs.
• Bulk Setup: ./setup.sh registers all local skills (defaults to remote mode to preserve skills-lock.json). Reserve this for full onboarding/re-sync (e.g. setting up a new machine), not routine single-skill edits. Use ./setup.sh --local for active development; the script automatically safeguards skills-lock.json from local path changes.
• Bulk Export: ./export.sh <domain> imports domain skills to a specific project.
• Manual Add: npx skills add <path_to_directory> -l to list all detectable skills.

Gem Export Workflow (Gem 導出流程)

Use this workflow to consolidate multiple skills into a single "Gem" instruction set for Google Gemini.

1. Identify Categories: Group related skills (e.g., Lifestyle, Development, Writing).
2. Extract Essence: For each skill, extract:
   • Core Role/Persona.
   • Mandates/Principles (Mandates prioritized).
   • Primary Workflows (Step-by-step).
3. Synthesize: Combine into a structured prompt:
   • # Role: A unified persona (e.g., "The Lifestyle Architect").
   • # Principles: Consolidated foundational concepts (e.g., Minerva HCs + Learning Principles).
   • # Capabilities: Categorized toolsets (Health, Learning, etc.).
   • # Interaction Style: Guidelines for tone and output.
4. Export: Write the result to gem/<category-name>.txt.

Plugin Export Workflow (Plugin 導出流程)

Use this workflow to bundle a set of existing skills (e.g. the user's most-used skills) into an installable Claude Code plugin, registered via a local marketplace.

1. Select Skills: Decide which skills to bundle. If ranking by usage, scan ~/.claude/projects/*/*.jsonl for Skill tool_use invocations (input.skill) and <command-name> slash-command tags — merge both, since some skills are only auto-triggered (no matching slash command) and some are only typed.
2. Verify Source Location: Confirm each selected skill actually resolves to a real directory under custom/<domain>/ or external/<domain>/. Do not bundle names that turn out to be built-in CLI commands, marketplace-plugin commands, or orphaned skills still sitting in .agents/skills/ (categorize those into custom//external/ first, per the SOPs below, before including them).
3. Scaffold the Plugin: Create <plugin-dir>/.claude-plugin/plugin.json (name, description, version, author) and <plugin-dir>/skills/. Inside skills/, symlink each bundled skill back to its real location (ln -s ../../custom/<domain>/<skill> <plugin-dir>/skills/<skill>) — never copy, so the plugin always tracks the canonical skill content. This makes the plugin local-only (not portable to a fresh clone without the rest of the repo); note that if the plugin is ever meant to be published externally.
4. Register a Marketplace: Create or update .claude-plugin/marketplace.json at the repo root ($schema, name, owner, plugins[] with each plugin's source as a relative path, e.g. "./<plugin-dir>").
5. Validate: Run /validate-skills against every symlinked skill (validation follows symlinks to the real SKILL.md, so this re-checks the canonical copy) and sanity-check both plugin.json and marketplace.json parse as valid JSON.
6. Document: Add a ## 🔌 Plugins entry to SKILLS_LIST.md listing the marketplace and each plugin, with the bundled skill names and links to their manifests.
7. Push: Commit the new plugin/marketplace files and the SKILLS_LIST.md update.
8. Install: /plugin marketplace add <repo-path> then /plugin install <plugin-name>@<marketplace-name>.

SOP for External Skills

1. Download: Run npx skills add <repo_path> in root (without -g) to inspect the skill.
2. Archive: Move from .agents/skills/ to external/<domain>/ (Ensure it is a direct child).
3. Validate: Run /validate-skills on the archived skill. Fix any FAIL items (name mismatch, body too long, bad link format, missing "when to use") before proceeding.
4. Document: Update SKILLS_LIST.md with the new skill's name, Chinese description, and link.
5. Push: Commit and push changes to GitHub.
6. Remote Install: Run npx skills add <user>/<repo>/external/<domain>/<skill-name> for that one skill — never ./setup.sh for a single-skill change.

SOP for Custom Skills

1. Create: Create skill directory in custom/<domain>/.
2. Implement: Write SKILL.md following skill-creator guidelines.
3. Validate: Run /validate-skills on the new skill. Fix any FAIL items before proceeding.
4. Document: Add the new skill to SKILLS_LIST.md.
5. Push: Commit and push changes to GitHub.
6. Remote Install: Run npx skills add <user>/<repo>/custom/<domain>/<skill-name> for that one skill — never ./setup.sh for a single-skill change.