Create Skill

Create Skill

Scaffold a new skill directly inside the chosen plugin of a local marketplace. The root skills/ folder is auto-generated by CI — do not create files there manually.

User's intention

$ARGUMENTS

References

Consult the relevant doc(s) before generating skill content in auto mode or before making structural decisions in manual mode:

• docs/skills.md — skill format, popular repositories, skills CLI
• docs/plugins.md — plugin structure, manifest, hooks and relative paths
• docs/hooks.md — hook lifecycle, PreToolUse / PostToolUse, hook scripts
• docs/marketplace.md — marketplace structure, registration, publishing, versioning, auto-updates
• docs/subagents.md — subagent usage, AGENTS.md format, coordination tips
• docs/rules.md — rules format and scope
• docs/mcp.md — MCP server configuration
• docs/memory.md — memory system, persistent memory for subagents
• docs/skills-cli.md — skills CLI commands
• docs/claude-code.md — Claude Code settings, commands, IDE integrations

Workflow

1. Create skill directory and SKILL.md — the form data submitted by the user was injected into your context as additionalContext by the UserPromptExpansion hook. It is a JSON object with mode and target fields.

   Target dispatch — the JSON includes a target field that determines where the skill lives:

   • target: "marketplace" — the JSON has marketplacePath and plugin. Write to <marketplacePath>/plugins/<plugin>/skills/<name>/SKILL.md.
   • target: "project" — the JSON has projectPath (the user's cwd). Write to <projectPath>/.claude/skills/<name>/SKILL.md. This is a project-local skill, not registered in any marketplace.

   Behaviour also depends on mode:

   Auto mode (mode: "auto") — the JSON contains { mode, target, name?, idea, useWhen, ...destination } where destination is either { marketplacePath, plugin } or { projectPath }:

   • Use name if provided, otherwise derive a concise kebab-case name from the idea.
   • Build the description frontmatter value:
     • Take the first sentence of idea as the "what" clause.
     • If useWhen is non-empty, append Use when + the chips joined naturally (Oxford-style with "or" before the last item). If empty, append Use when <trigger condition>. as a placeholder.
     • Clip the full description to 140 characters.
   • Generate complete, ready-to-use SKILL.md content: a clear workflow, concrete steps, and any relevant reference tables or decision trees — as if a domain expert wrote it. Do not leave placeholder text.

   Manual mode (mode: "manual") — the JSON contains { mode, target, name, description, triggers, ...destination }:

   • Use all provided values as-is.
   • Build the description frontmatter: "<description>. Use when <triggers joined with ', ' and 'or' before the last>." If triggers is empty, use the raw description only.
   • Create a minimal skeleton the user will fill in:

   ---
   name: <name>
   description: "<built description>"
   ---
   
   # <Title Case of name>
   
   Add instructions here. Structure freely: step-by-step workflow, reference tables, decision trees — whatever fits the skill.
   
   Optional subdirectories (create only if needed):
   
   - `scripts/` — executable helpers (Node.js, Python, shell)
   - `references/` — supporting docs or templates
   - `assets/` — static files (images, data)
   

2. Hooks If the skill needs a hook (e.g. to collect input before the skill runs), add it to the plugin instead of user settings so it's distributed automatically. See Hooks and Relative Paths.

3. Report to user

   • Report the path where the skill was created:
     • Marketplace target: <marketplacePath>/plugins/<plugin>/skills/<name>/SKILL.md
     • Project target: <projectPath>/.claude/skills/<name>/SKILL.md
   • Next steps:
     • Fill in the new SKILL.md with instructions
     • Add scripts/ or references/ dirs if the skill needs helper files
     • For marketplace targets only: update the marketplace so the skill becomes visible: claude plugin marketplace update
     • Project skills are picked up automatically by Claude Code running in that project.