feat: add meta-skill create-skill for creating and improving skills

Two modes: Create (gather requirements, generate SKILL.md) and Improve (diagnose existing skill against best practices, propose changes). Includes bundled references for frontmatter spec and writing guide. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 18:24:55 +02:00
parent 9931269907
commit ea21818f76
3 changed files with 298 additions and 0 deletions
--- a/.claude/skills/create-skill/SKILL.md
+++ b/.claude/skills/create-skill/SKILL.md
@@ -0,0 +1,119 @@
+---
+name: create-skill
+description: Create or improve a Claude Code skill — gathers requirements, selects agent type and frontmatter, generates a SKILL.md following best practices. Use when the user wants to create a skill, turn a workflow into a skill, improve an existing skill, or automate a repeating task as a slash command.
+disable-model-invocation: true
+argument-hint: "[skill-name or 'improve existing-skill-name']"
+---
+
+# Create or Improve Skill
+
+Target: `$ARGUMENTS`
+
+## Context
+
+Existing project skills:
+!`ls .claude/skills/ 2>/dev/null`
+
+## Detect Mode
+
+- If `$ARGUMENTS` names an existing skill (check dirs above) → **Improve mode**
+- Otherwise → **Create mode**
+
+---
+
+## Create Mode
+
+### 1. Capture intent
+
+Check if the current conversation already contains a workflow the user wants to turn into a skill. If so, extract: tools used, sequence of steps, corrections made, input/output formats. Confirm with the user before proceeding.
+
+If no prior context, gather requirements:
+- What does this skill do? (one sentence)
+- When should someone use it? (trigger phrases, contexts)
+- What arguments does it expect? (file path, name, or none)
+- Does it produce new files, modify existing files, or output analysis?
+- Does it need live data at invocation time? (git diff, shell output)
+- Scope: personal skill (all projects) or project-only?
+
+### 2. Research
+
+Read 2-3 existing skills closest in nature to the user's intent. Use them as examples of project conventions.
+
+Read `${CLAUDE_SKILL_DIR}/references/frontmatter-spec.md` for the complete frontmatter specification.
+Read `${CLAUDE_SKILL_DIR}/references/writing-guide.md` for skill writing best practices.
+
+### 3. Determine frontmatter
+
+Select the appropriate `agent` based on domain:
+
+| Agent | Domain |
+|---|---|
+| `frontend-architect` | UI, components, accessibility |
+| `backend-architect` | APIs, databases, server logic |
+| `code-reviewer` | Code review, quality analysis |
+| `test-engineer` | Tests, test strategy |
+| `security-auditor` | Security, threat modeling |
+| `prompt-engineer` | Prompts, LLM config |
+| `documentation-expert` | Docs, ADRs |
+| _(omit + no fork)_ | Multi-file coordination, interactive workflows |
+
+Decide: `context: fork` for standalone deliverables (new file, analysis report). Omit for interactive workflows or multi-file coordination.
+
+Always include `disable-model-invocation: true` (project convention).
+
+### 4. Write the SKILL.md
+
+Structure:
+- H1 title — short action phrase
+- One-liner referencing `$ARGUMENTS`
+- Context section (optional) — `!` backtick for live data
+- Steps — numbered, imperative:
+  - Step 1: read project context
+  - Middle: core logic
+  - Last: output or summary
+- Output format (if structured) — markdown template in fenced block
+
+### 5. Write file
+
+Based on scope choice:
+- Personal: `~/.claude/skills/$NAME/SKILL.md`
+- Project: `.claude/skills/$NAME/SKILL.md`
+
+### 6. Verify and suggest tests
+
+Read back the file and check:
+- [ ] Valid YAML frontmatter
+- [ ] Lowercase-hyphen name, no collision with existing skills
+- [ ] Description with trigger contexts (slightly "pushy")
+- [ ] Body: H1, steps, $ARGUMENTS reference
+- [ ] Length appropriate (30-70 focused, up to 500 complex)
+
+Propose 2-3 realistic test prompts including one edge case.
+
+---
+
+## Improve Mode
+
+### 1. Read the existing skill
+
+Read the full SKILL.md and any bundled resources in its directory.
+
+### 2. Diagnose issues
+
+Read `${CLAUDE_SKILL_DIR}/references/writing-guide.md` for evaluation criteria.
+
+Analyze against:
+- Description quality — is it "pushy" enough? Does it cover trigger contexts?
+- Instruction clarity — does it explain WHY, not just rules?
+- Structure — follows project conventions?
+- Length — is it concise or bloated?
+- Filler — does every sentence change agent behavior?
+
+### 3. Propose improvements
+
+Show a before/after diff of proposed changes with rationale for each change.
+Apply only after user approval.
+
+### 4. Suggest test prompts
+
+Propose 2-3 prompts to verify the improved skill works as expected.
--- a/.claude/skills/create-skill/references/frontmatter-spec.md
+++ b/.claude/skills/create-skill/references/frontmatter-spec.md
@@ -0,0 +1,83 @@
+# Frontmatter Specification
+
+Complete reference for SKILL.md YAML frontmatter fields.
+
+## Required Fields
+
+### `name`
+- Lowercase-hyphen format: `my-skill-name`
+- Max 64 characters
+- Must be unique across all skill directories
+- Becomes the slash command: `/my-skill-name`
+
+### `description`
+- One sentence, under 200 characters
+- Should be slightly "pushy" — describe WHEN to use the skill, not just what it does
+- Include trigger contexts so the model selects the skill proactively
+- Good: "Scaffold a new React component with TypeScript, accessibility, all states, and variant support via cva."
+- Bad: "Creates components."
+- Pattern: `[Action verb] [what] — [key details]. Use when [trigger contexts].`
+
+## Optional Fields
+
+### `disable-model-invocation`
+- `true` — skill only runs when user invokes via `/name`
+- `false` (default) — model can auto-invoke when description matches user intent
+- Project convention: always set to `true`
+
+### `user-invocable`
+- `true` (default) — appears as a slash command
+- `false` — background knowledge only, used as reference by other skills
+
+### `argument-hint`
+- Shown in autocomplete: `/skill-name [hint]`
+- Use brackets for placeholders: `"[file-or-directory]"`, `"[ComponentName]"`
+- Omit if the skill takes no arguments
+
+### `context`
+- `fork` — runs in a forked context (separate conversation branch)
+  - Use for: standalone deliverables, analysis reports, code generation that doesn't need follow-up
+  - The skill gets its own clean context with only the skill instructions
+- Omit (no fork) — runs in the main conversation context
+  - Use for: interactive workflows, multi-step conversations, skills that need conversation history
+  - When omitted, `agent` field should also be omitted
+
+Decision tree:
+1. Does the skill need conversation history? → no fork
+2. Does the skill ask the user questions mid-flow? → no fork
+3. Does the skill produce a single standalone output? → fork
+4. Is it a one-shot analysis or generation? → fork
+
+### `agent`
+- Assigns a specialized agent persona. Only meaningful with `context: fork`.
+- Available agents:
+
+| Agent | Use for |
+|---|---|
+| `frontend-architect` | UI, components, CSS, accessibility, browser APIs |
+| `backend-architect` | APIs, databases, server logic, system design |
+| `code-reviewer` | Code review, quality analysis, diff review |
+| `test-engineer` | Test writing, test strategy, coverage analysis |
+| `security-auditor` | Security audit, threat modeling, vulnerability analysis |
+| `prompt-engineer` | Prompt design, LLM configuration, prompt evaluation |
+| `documentation-expert` | Documentation, ADRs, technical writing |
+
+- Omit when: no fork, or skill doesn't fit a specific domain
+
+### `allowed-tools`
+- Restrict which tools the skill can use
+- Comma-separated list: `allowed-tools: Read, Grep, Glob`
+- Omit to allow all tools (default)
+
+### `model`
+- Override the model for this skill
+- Example: `model: claude-sonnet-4-6`
+- Omit to use the default model
+
+### `hooks`
+- Lifecycle event handlers (pre/post execution)
+- Rarely needed for most skills
+
+### `compatibility`
+- Declare dependencies or requirements
+- Example: `compatibility: node>=18`
--- a/.claude/skills/create-skill/references/writing-guide.md
+++ b/.claude/skills/create-skill/references/writing-guide.md
@@ -0,0 +1,96 @@
+# Skill Writing Guide
+
+Best practices for writing effective Claude Code skills.
+
+## Two Categories of Skills
+
+1. **Capability uplift** — teaches the agent something it couldn't do before (scaffold component, run audit, deploy)
+2. **Encoded preference** — captures your specific way of doing something the agent could already do (commit style, review checklist, naming conventions)
+
+Know which you're building — it changes how much detail to include.
+
+## Description Optimization
+
+The description is the most important line. It determines when the skill gets triggered.
+
+- List trigger contexts explicitly: "Use when the user wants to X, Y, or Z"
+- Think about should-trigger / should-not-trigger scenarios
+- A slightly "pushy" description is better than a vague one
+- Test: would this description make the model select this skill for the right prompts?
+
+## Writing Instructions
+
+### Explain WHY, not just rules
+- Bad: "MUST use semantic HTML"
+- Good: "Use semantic HTML elements (nav, main, aside) because screen readers depend on landmarks for navigation"
+
+### Avoid heavy-handed MUSTs
+- Reserve MUST/NEVER for genuine constraints (security, data loss)
+- For preferences, explain the reasoning and let the agent make good decisions
+
+### Progressive disclosure
+Three levels of instruction loading:
+1. **Frontmatter** — always loaded (name, description). Keep minimal.
+2. **Body** — loaded when skill is invoked. Core instructions here.
+3. **Bundled resources** — loaded on demand via `Read`. Put reference tables, specs, examples here.
+
+Use bundled resources (`references/`, `scripts/`, `assets/`) for content that would bloat the main SKILL.md.
+
+### Every sentence should change behavior
+- Delete filler: "It is important to...", "Make sure to...", "Please note that..."
+- Delete obvious instructions the agent would do anyway
+- Test: if you removed this sentence, would the output change? No → delete it.
+
+## Structure Conventions
+
+### Project conventions (this repo)
+- Always set `disable-model-invocation: true`
+- Use H1 for the skill title (short action phrase)
+- Reference `$ARGUMENTS` early in the body
+- Use `!` backtick for live data injection (git diff, file listings)
+- Numbered steps, imperative voice
+- Output format in a fenced markdown block if structured
+
+### Bundled resources pattern
+```
+.claude/skills/my-skill/
+  SKILL.md              # Main instructions
+  references/           # Specs, guides, schemas
+  scripts/              # Shell scripts, templates
+  assets/               # Static files
+```
+
+Reference from SKILL.md: `Read ${CLAUDE_SKILL_DIR}/references/spec.md`
+
+## Length Guidelines
+
+- Simple skills (encoded preference): 30-50 lines
+- Standard skills (capability uplift): 50-100 lines
+- Complex skills (multi-mode, research): 100-200 lines
+- Maximum: 500 lines (if exceeding, split into bundled resources)
+
+## Common Mistakes
+
+1. **Overfitting to test cases** — write general instructions, not scripts for specific inputs
+2. **Too many rules** — the agent ignores rules after ~20 constraints. Prioritize.
+3. **No examples** — for complex output formats, show one complete example
+4. **Ignoring conversation context** — skills without fork can use prior conversation. Leverage it.
+5. **Forgetting edge cases** — what happens with empty input? Invalid arguments? Missing files?
+
+## Improvement Workflow
+
+1. Draft the skill
+2. Test with 3-5 realistic prompts
+3. Review output — does every instruction change behavior?
+4. Remove filler, tighten descriptions
+5. Add edge case handling for failures observed in testing
+6. Re-test after changes
+
+## Evaluation Criteria
+
+When reviewing a skill, score against:
+- **Trigger accuracy** — does the description match the right prompts?
+- **Instruction clarity** — can the agent follow without ambiguity?
+- **Output quality** — does the skill produce useful, consistent results?
+- **Conciseness** — is every line earning its place?
+- **Robustness** — does it handle edge cases and errors?