# Skill Builder

> Build new Claude Code skills with best-practice enforcement from Anthropic's official skill guide. Handles use case definition, pattern selection, frontmatter generation, instruction writing, validation, and test case generation. Use when user says "build a skill", "create a skill", "make a new skill", "turn this into a skill", "I want a skill for", "skill for [X]", "make me a slash command", or "new skill that [does something]". Do NOT use for running evals or benchmarking existing skills (use skill-eval for that). Do NOT use for listing, deleting, or inspecting existing skills.

- Skill: `gridlock-nyc/skill-builder` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add gridlock-nyc/skill-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gridlock-nyc/skill-builder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: GRIDLOCK-NYC (https://skillmd.com/u/gridlock-nyc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gridlock-nyc/skill-builder

---


# Skill Builder

Build structurally correct Claude Code skills by enforcing Anthropic's official skill guide patterns, rules, and validation checklist.

## Important

- Take your time with each phase. Quality is more important than speed.
- Do not skip validation steps — every check matters.
- Read the referenced files in `references/` before making decisions that depend on them. They contain the authoritative rules.
- Explain the *why* behind structural decisions so the user builds intuition, not just files.

## Instructions

This skill runs a 4-phase workflow with exactly **2 pauses** (Phase 1 and Phase 4). Phases 2 and 3 execute automatically.

---

### Phase 1: Extract Intent (1 pause)

Determine which entry path applies:

#### Path A — From Conversation Context

If the user said "turn this into a skill" or similar, referring to work already done in the conversation:

1. Review the conversation history for: tools used, step sequence, corrections made, input/output formats, domain knowledge applied.
2. Synthesize a summary: "Here's what I extracted from our conversation: [summary]."
3. Pause for confirmation: "Does this capture it, or should I adjust?"

#### Path B — From Intent Argument

If the user provided `$ARGUMENTS` or described what they want:

1. Ask the 4 intent questions (one message, one pause):
   - What does the user want to accomplish with this skill?
   - What multi-step workflows does this require?
   - Which tools are needed (built-in like Read/Write/Bash/Grep/Glob, or MCP servers)?
   - What domain knowledge or best practices should be embedded?
2. Pause once for answers.

#### Path C — Idea Development

If the user wants to explore or develop a skill concept before committing to building it (e.g., "help me develop this idea", "I need a skill that can...", "what would this look like"):

1. Engage in structured collaboration:
   - Clarify the core problem the skill solves
   - Identify what makes it hard (domain knowledge, multi-step coordination, tool selection, etc.)
   - Propose the output format and key decisions
   - Surface design tensions and tradeoffs
2. Do NOT ask the 4 intent questions mechanically. Have a real conversation about the concept.
3. Pause as many times as needed — this path is collaborative, not a form.
4. **Exit condition**: When the user says "build it", "go ahead", "go for it", or equivalent approval, transition to Auto-Decisions below and proceed through Phases 2-4 automatically.

#### Auto-Decisions (after the pause)

After receiving confirmation (Path A) or answers (Path B):

1. **Read reference files first.** Before making any decisions, read `references/patterns.md`, `references/frontmatter-rules.md`, and `references/description-craft.md`. These inform the decisions below.
2. Make these decisions automatically. State each one clearly:

**Use Case Category** — Classify as one of:
- **Document & Asset Creation**: Skill produces files, reports, documentation, or structured output
- **Workflow Automation**: Skill orchestrates a multi-step process (build, deploy, test, etc.)
- **MCP Enhancement**: Skill teaches optimal workflows for connected MCP servers

State: "Category: [X] because [reason]."

**Framing** — Choose one:
- **Problem-first**: User describes a goal, skill orchestrates tools to achieve it. ("I need to set up a workspace")
- **Tool-first**: User has specific tools/MCPs, skill teaches optimal usage patterns. ("I have Notion MCP connected")

State: "Framing: [X] because [reason]."

**Pattern** — Choose from the 5 patterns (already read in step 1 above):
1. Sequential Workflow
2. Multi-MCP Coordination
3. Iterative Refinement
4. Context-Aware Tool Selection
5. Domain-Specific Intelligence

State: "Pattern: [X] because [reason]."

**Location** — Determine where to save:
- If the skill is project-specific (only useful in this repo): `{project}/.claude/skills/{skill-name}/`
- If the skill is general-purpose (useful across projects): `~/.claude/skills/{skill-name}/`
- When in doubt, prefer global (`~/.claude/skills/`) — skills can always be moved later

State: "Location: [path]"

**Invocability** — Default to `user_invocable: true` unless the skill is clearly meant to be auto-triggered only.

Proceed immediately to Phase 2.

---

### Phase 2: Build (0 pauses)

Construct the entire skill. Do not pause during this phase.

#### Step 1: Create Folder

- Name in kebab-case (no spaces, underscores, or capitals)
- Create the folder and `references/` subdirectory if needed

#### Step 2: Generate Frontmatter

Consult `references/frontmatter-rules.md` (already read in Phase 1) for the complete rule set.

Required fields:
- `name`: kebab-case, must match folder name, no "claude" or "anthropic" in the name
- `description`: Craft using the formula from `references/description-craft.md`:
  - Structure: `[What it does] + [When to use it] + [Key capabilities]`
  - Under 1024 characters
  - No XML tags (`<` or `>`)
  - Include specific trigger phrases users would actually say
  - Include negative triggers if scope could be confused with another skill
  - Be "a little pushy" on triggers — Claude undertriggers by default, so lean inclusive
- `user_invocable`: true by default
- `argument`: include if the skill accepts input

Optional fields — only include when genuinely needed:
- `compatibility`: environment requirements (1-500 chars)
- `metadata`: author, version, mcp-server
- `license`: MIT, Apache-2.0, etc.

#### Step 3: Write Instructions

Apply the pattern selected in Phase 1 to structure the instructions. Follow these rules:

**Voice and form:**
- Imperative form: "Run X", "Check Y" — not "You should run X"
- Every instruction is a concrete action, never vague
- GOOD: `Run \`python scripts/validate.py --input {filename}\` to check data format`
- BAD: `Validate the data before proceeding`

**Structure:**
- Start with `# Skill Name`
- Add `## Important` or `## Critical` header at top for must-follow rules
- Use `## Instructions` with `### Step N: [Action]` subsections
- Include `## Error Handling` section with concrete numbered fixes
- Include `## Examples` section with input/output format for common scenarios
- Reference bundled resources: "Before doing X, consult `references/Y.md` for the complete rule set"

**Quality enforcement:**
- Add performance notes: "Take your time", "Quality is more important than speed", "Do not skip validation steps"
- Explain the why behind non-obvious decisions — theory of mind beats heavy-handed MUSTs
- Critical instructions go at the top, not buried in the middle

**Progressive disclosure:**
- Core instructions in SKILL.md, detailed docs in `references/`
- Keep SKILL.md under 500 lines
- If approaching the limit, add hierarchy and clear pointers to reference files

#### Step 4: Create References (if needed)

Only create `references/` files for skills with:
- Domain knowledge that would bloat SKILL.md
- API patterns or templates
- Multiple variants or modes

For simple skills (~50 lines of instructions), skip references entirely.

When creating reference files:
- Include table of contents for files over 300 lines
- Organize by variant/domain if supporting multiple contexts

#### Step 5: No README.md

Never create a README.md inside the skill folder. SKILL.md is the only documentation file.

---

### Phase 3: Validate (0 pauses)

Run every check from the validation checklist automatically. Read `references/validation-checklist.md` for the full list.

**Validation checks to run:**

1. Folder named in kebab-case
2. SKILL.md exists (exact spelling, case-sensitive)
3. YAML frontmatter has `---` delimiters
4. `name` field: kebab-case, no spaces, no capitals
5. `name` matches folder name
6. `description` includes WHAT and WHEN components
7. `description` under 1024 characters
8. No XML tags (`<` or `>`) in any frontmatter field
9. Instructions use imperative form (spot-check first 5 action sentences)
10. Error handling section present
11. Examples section present
12. References clearly linked (if `references/` exists)
13. No README.md in skill folder
14. SKILL.md under 500 lines

**Print the validation report:**

```
Validation Report:
  [PASS] Folder named in kebab-case
  [PASS] SKILL.md exists (exact spelling)
  [PASS] YAML frontmatter has --- delimiters
  ...
```

If any check **fails**: fix the issue immediately, re-validate, and show the corrected report. Do not present a report with failures unless the fix requires user input.

---

### Phase 4: Deliver (1 pause)

Present the finished skill:

1. **Show the full frontmatter** — the YAML block between `---` delimiters
2. **Show instruction structure** — headers and step names (not the full content)
3. **State the pattern** applied and why it was chosen
4. **Provide test prompts:**
   - 2-3 should-trigger prompts:
     - One obvious task description
     - One paraphrased/indirect request
     - One edge case that should still trigger
   - 2 should-NOT-trigger prompts:
     - Near-misses that share keywords but need a different skill or no skill
     - These are the most valuable tests for preventing overtriggering
5. **State location** and how to invoke: `/skill-name` or natural language

Ask: "Anything to adjust, or ready to use? Run `/skill-eval` to benchmark how well this skill follows its own instructions."

---

## Error Handling

### Folder already exists
1. Check contents. If it contains an existing skill, ask the user: overwrite or pick a new name?
2. Never silently overwrite.

### SKILL.md exceeds 500 lines
1. Identify sections that can move to `references/`
2. Extract them, replace with pointers: "See `references/X.md` for details"
3. Re-validate line count

### Description exceeds 1024 characters
1. Tighten language — remove redundant trigger phrases
2. Keep the WHAT + WHEN + negative triggers structure
3. Cut capabilities list if needed (triggers matter more)

### Frontmatter validation fails
1. Fix the specific field
2. Re-run validation
3. Show corrected report

## Examples

### Example 1: Simple workflow skill

**User**: `/skill-builder a skill that runs my Python test suite with coverage`

**Result**: A sequential-workflow skill with:
- Frontmatter with triggers like "run tests", "test coverage", "pytest"
- Steps: discover test files, run pytest with coverage flags, parse output, report results
- Error handling for missing dependencies, no tests found, failures
- Examples showing different invocation patterns

### Example 2: From conversation

**User** (after debugging session): "turn this into a skill"

**Result**: Extracts the debugging workflow from conversation, builds a domain-specific intelligence skill with the diagnostic patterns embedded, triggers on relevant error types.

### Example 3: MCP-enhanced skill

**User**: `/skill-builder a skill for managing GitHub issues with labels and milestones`

**Result**: A multi-MCP coordination skill (if GitHub MCP is available) or sequential workflow (if using gh CLI), with triggers for "create issue", "label issues", "milestone planning".