create-skill

Scaffold a new Claude Code skill or command and register it in the README. Automatically determines whether the addition is better suited as a skill (rich multi-step workflow) or a command (lightweight single action) based on the audit criteria below, then asks the user to confirm or override before scaffolding.

• $0 is the name in kebab-case (e.g., create-pr)
• $1 (and everything after the name) is an optional one-sentence description

If $ARGUMENTS is empty, ask the user for the name and description before proceeding.

Steps

1. Validate the name:

   • Confirm $0 is kebab-case (lowercase letters and hyphens only). If not, convert it and tell the user.
   • Check that neither skills/$0/ nor commands/$0.md already exists in the target plugin. If either does, stop and tell the user it already exists.

2. Read existing files for reference: Read one or two existing SKILL.md files and one command .md file (if any exist) from the plugin directory to confirm current conventions before writing anything.

3. Determine the description: Use $1 if provided. If not, ask the user for a one-sentence description before continuing.

4. Determine the type — evaluate the description against these five signals:

   Signal	Favors Skill	Favors Command
   Step count	Would need 3+ steps with branching or conditional logic	Would need 1–2 simple linear steps
   Context needs	Requires domain knowledge or codebase understanding	Needs only file paths or simple args
   Tool variety	Would use 3+ different tools	Would use mainly Bash or Write alone
   Output complexity	Produces structured analysis, reports, or multi-file changes	Produces a single file or simple output
   Bundled resources	Would benefit from scripts/, references/, or assets/	None needed

   • Count how many signals favor skill vs command.
   • Majority wins; ties default to skill.
   • Present the recommendation to the user with a one-line justification per signal.
   • Ask the user to confirm or override the recommendation before continuing.

5. Scaffold based on determined type:

   If skill — create <plugin>/skills/$0/SKILL.md with this structure:

   ---
   name: <name>
   description: <description>
   argument-hint: "[arguments]"
   allowed-tools:
   
   - Bash
   - Read
   - Write
   - Edit
   - Glob
   - Grep
   
   ---
   
   <One paragraph explaining what this skill does and when to use it.>
   
   ## Steps
   
   1. **Step one**: Description of the first step.
   
   2. **Step two**: Description of the second step.
   
   3. **Step three**: Description of the third step.
   
   ## Important
   
   - Key constraint or safety rule.
   - Another constraint.
   

   • Set name to $0 and description to the agreed description.
   • Set argument-hint only if the skill takes arguments; remove the field entirely if it takes none.
   • Remove tools from allowed-tools that the skill clearly won't need.
   • Leave the Steps and Important sections as explicit placeholders — do not invent steps.

   If command — create <plugin>/commands/$0.md with this structure:

   ---
   name: <name>
   description: <description>
   argument-hint: "[arguments]"
   allowed-tools:
   
   - Write
   
   ---
   
   <One sentence explaining what this command does.>
   
   - Bullet point describing key behavior.
   - Another bullet point.
   

   • Set name to $0 and description to the agreed description.
   • Set argument-hint only if the command takes arguments; remove the field entirely if it takes none.
   • Include only the tools the command actually needs in allowed-tools (commands typically use 1–2).
   • Leave the bullet points as explicit placeholders — do not invent behavior.

6. Update README.md: If a README.md exists in the repo root, add a row to the appropriate per-plugin table:

   • For skills: | \/ [args]` | |` under a Skill column header
   • For commands: | \/ [args]` | |` under a Command column header
   • Update the plugin catalog table's skill count if needed (e.g., "5" → "5 skills, 1 command").

7. Report: Tell the user what was created, where, and which type. For skills, remind them to fill in the Steps and Important sections. For commands, remind them to fill in the bullet points.

Important

• Never overwrite an existing skill or command — check first and stop if it already exists.
• Do not invent behavior for placeholders. The scaffolded steps/bullets are intentional placeholders.
• Mirror the whitespace, heading style, and frontmatter format exactly as found in existing files.
• If the skills/commands directory is somewhere other than the expected location, infer the correct path from where existing files are located.
• The type determination is a recommendation, not a mandate — always let the user override.