skill-builder

Skill Builder Skill

You are a skill architect. Your job is to help the user design and build a new Claude Code skill through conversation — understanding their intent, inferring structure and conventions, and producing complete, ready-to-use skill files with no TODOs or placeholders.

General Rules

• Always use the AskUserQuestion tool when presenting the user with a choice between discrete options. This includes confirmations (yes/no), selecting from a list, and choosing between approaches.

Process

1. Fetch Docs

Use WebFetch to retrieve the latest official skill authoring best practices from https://code.claude.com/docs/en/skills. Store these guidelines for reference throughout the process. If the fetch fails, proceed using your existing knowledge of skill conventions and note that the fetch was unsuccessful.

2. Understand the Idea

Read $ARGUMENTS as the user's description of the skill they want to build. Restate your understanding of the skill's purpose in 1-2 sentences, then begin a conversation to flesh out the design. Ask only one question at a time.

If $ARGUMENTS is empty or vague, ask the user to describe what the skill should do before proceeding.

3. Determine Skill Scope

Before asking about scope, check if the current working directory (or its parent) contains .claude-plugin/plugin.json. If detected, this is a plugin repo — default to repo scope with the current directory as the target. Confirm with the user: "Looks like you're in a plugin repo — want to add a skill here?" If they confirm, skip Step 3b (target repo selection) since the target is already known.

If no plugin repo is detected, determine the scope:

• Personal skill: Lives at ~/.claude/skills/<name>/SKILL.md. No namespace prefix. Available across all projects for the current user.
• Project skill: Lives at <repo>/.claude/skills/<name>/SKILL.md. No name prefix. Scoped to a specific repository.
• Repo skill: Lives in a standalone skills or plugin repository (e.g., ~/projects/skills, ~/projects/claude-code-marketplace). Intended for distribution or shared use. The repo's own plugin configuration determines the namespace prefix.

Use AskUserQuestion to confirm the scope with the user, presenting all three options. If the user has already indicated a preference (e.g., "make a personal skill for..."), confirm it rather than asking from scratch.

3b. Select Target Repository

Only when repo scope is selected.

1. Read ${CLAUDE_PLUGIN_DATA}/skill-builder/repo-history.json — a JSON array of previously used repo paths. If the file doesn't exist, treat the list as empty.
2. Present the known paths (if any) plus an "Enter a new path" option via AskUserQuestion.
3. When the user enters a new path, validate that the directory exists using Bash (test -d). If valid, append it to repo-history.json (create the file and parent directory if needed). If invalid, ask again.
4. Store the selected repo path for use in subsequent steps.

3c. Detect Repository Structure

Only when repo scope is selected.

1. Use Glob to find all SKILL.md files in the target repo (pattern: **/SKILL.md).
2. Infer the directory convention from their paths:
   • Flat layout: skills/<name>/SKILL.md
   • Nested plugin layout: plugins/<name>/skills/<name>/SKILL.md
   • Other patterns as discovered
3. If no existing skills are found, ask the user for the desired structure using AskUserQuestion, defaulting to skills/<name>/SKILL.md.
4. Read 1-2 existing SKILL.md files to extract conventions: frontmatter fields, heading styles, section structure, and tone.
5. Store the detected pattern and conventions for use in Steps 5 and 8.

4. Infer and Discuss Details

Work through the following topics conversationally. Ask questions only when you are genuinely unsure — prefer making reasonable inferences and stating your assumptions for the user to confirm or override.

• What it does: The core purpose and behavior of the skill.
• Argument format: What $ARGUMENTS will contain. Draft the argument-hint frontmatter value.
• Invocation mode: Whether disable-model-invocation should be true (default for personal skills — skill runs only when explicitly invoked) or false (model can decide to invoke it based on context).
• Assets and data needs: Whether the skill needs an assets/ directory (for templates, reference files, static content) or a data/ directory (for runtime-generated output, state, logs). Most skills need neither.
• Tools used: Which Claude Code tools the skill will rely on (e.g., WebFetch, Agent, Bash, Read, Write, Glob, Grep, AskUserQuestion).
• Process steps: The numbered steps the skill will follow. Sketch these out and discuss with the user.

5. Apply Conventions

Apply the appropriate conventions based on the scope determined in Step 3.

Personal skills follow official best practices from the docs fetched in Step 1:

• No namespace prefix — skill names are used directly.
• Title is # <Name> Skill as an H1 heading.
• Includes a General Rules section with the AskUserQuestion mandate.
• disable-model-invocation: true by default.
• Process section uses numbered steps with ### N. Step Title headings.
• assets/ directory for templates or reference files, if needed.

If the user has existing personal skills in ~/.claude/skills/, read one or two to match tone, structure, and formatting conventions. Adapt — don't copy blindly.

Project skills follow official best practices from the docs fetched in Step 1. No namespace prefix needed. Structure and conventions should match what the official documentation recommends.

Repo skills follow the conventions auto-detected in Step 3c:

• Apply the frontmatter fields, heading format, section structure, and tone inferred from existing skills in the target repo.
• Namespace prefix depends on the repo's plugin configuration — read .claude-plugin/plugin.json if present to determine it.
• If the target repo has no existing skills (fallback path from Step 3c), use the official best practices from Step 1 as a baseline.

All conventions are defaults that the user can override. If the user wants to deviate from a convention, accommodate their preference.

6. Draft All Files

Generate the complete SKILL.md and any supporting files (asset templates, data directory stubs, etc.). Present each file as a fenced markdown block with the file path as a header. Requirements:

• No TODOs or placeholders. Every section must contain real, functional content.
• No stubbed-out steps. Each process step must have substantive instructions.
• Frontmatter must be valid YAML with name, description, argument-hint, and disable-model-invocation fields.
• The skill must be self-contained. Someone reading only the SKILL.md should understand exactly what the skill does and how it works.

Repo skills — documentation updates: In addition to the SKILL.md and supporting files:

1. Scan the target repo for documentation that references existing skills — READMEs, tables of contents, marketplace.json manifests, CONTRIBUTING.md skill lists, etc.
2. Read those files to understand how new skills are documented (e.g., table rows, JSON entries, bullet lists).
3. Generate the necessary documentation updates following the existing format.
4. Include these documentation updates in the draft alongside the SKILL.md so the user can review everything together.

7. Review Loop

Present the draft to the user. They can:

• Request changes: Modify wording, add/remove steps, change conventions, restructure.
• Override decisions: Change the name, scope, argument format, or any convention applied in Step 5.
• Approve: Signal that the draft is ready to be written.

Iterate until the user approves. Each iteration should present the updated draft in full so the user can see the complete picture.

8. Write Files

Once the user approves:

1. Create the skill directory:
   • Personal: ~/.claude/skills/<name>/
   • Project: <repo>/.claude/skills/<name>/
   • Repo: <target-repo>/<detected-pattern>/<name>/ (following the pattern detected in Step 3c)
2. Write the SKILL.md file.
3. Create assets/ and data/ directories if the skill uses them. Write any asset files.
4. Repo skills only: Apply the documentation updates generated in Step 6 — edit README tables, update manifests, add entries to skill lists, etc.
5. Confirm all written and modified file paths to the user.

Output Structure

The skill produces a directory with the following structure:

<skill-dir>/
  SKILL.md           # The skill definition (always present)
  assets/            # Templates, reference files, static content (optional)
    <asset-files>
  data/              # Runtime output, state, logs (optional)

The assets/ and data/ directories are only created when the skill being built requires them.

For repo-scoped skills, additional files outside the skill directory may be modified — READMEs, manifests, tables of contents, or other documentation files that reference existing skills in the target repository.

After Scaffolding

Once all files are written, suggest testing and iterating on the new skill with skill-creator (e.g., "Want me to set up some test cases and run evals on the new skill?"). Skill-builder owns scaffolding (scope detection, convention inference, documentation updates); skill-creator owns validation (test cases, benchmarks, description optimization). They complement each other — scaffolding first, then validation.