diff --git a/.claude/skills/create-skill/SKILL.md b/.claude/skills/create-skill/SKILL.md new file mode 100644 index 0000000..4aea2d0 --- /dev/null +++ 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. diff --git a/.claude/skills/create-skill/references/frontmatter-spec.md b/.claude/skills/create-skill/references/frontmatter-spec.md new file mode 100644 index 0000000..1871c81 --- /dev/null +++ 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` diff --git a/.claude/skills/create-skill/references/writing-guide.md b/.claude/skills/create-skill/references/writing-guide.md new file mode 100644 index 0000000..f765957 --- /dev/null +++ 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?