skill-maker

# Skill Maker ## Protocols <!-- protocol injection (was: !`cat Claude-Production-Grade-Suite/.protocols/ux-protocol.md 2>/dev/null || true`) --> Read protocol: `${PG_PROTOCOLS}/ux-protocol.md` (use the `read_file` tool before continuing). <!-- protocol injection (was: !`cat Claude-Production-Grade-Suite/.protocols/input-validation.md 2>/dev/null || true`) --> Read protocol: `${PG_PROTOCOLS}/input-validation.md` (use the `read_file` tool before continuing). <!-- protocol injection (was: !`cat Claude-Production-Grade-Suite/.protocols/tool-efficiency.md 2>/dev/null || true`) --> Read protocol: `${PG_PROTOCOLS}/tool-efficiency.md` (use the `read_file` tool before continuing). <!-- protocol injection (was: !`cat Claude-Production-Grade-Suite/.protocols/visual-identity.md 2>/dev/null || true`) --> Read protocol: `${PG_PROTOCOLS}/visual-identity.md` (use the `read_file` tool before continuing). <!-- protocol injection (was: !`cat Claude-Production-Grade-Suite/.protocols/freshness-protocol.md 2>/dev/null || true`) --> Read protocol: `${PG_PROTOCOLS}/freshness-protocol.md` (use the `read_file` tool before continuing). <!-- protocol injection (was: !`cat Claude-Production-Grade-Suite/.protocols/receipt-protocol.md 2>/dev/null || true`) --> Read protocol: `${PG_PROTOCOLS}/receipt-protocol.md` (use the `read_file` tool before continuing). <!-- protocol injection (was: !`cat Claude-Production-Grade-Suite/.protocols/boundary-safety.md 2>/dev/null || true`) --> Read protocol: `${PG_PROTOCOLS}/boundary-safety.md` (use the `read_file` tool before continuing). <!-- protocol injection (was: !`cat Claude-Production-Grade-Suite/.protocols/conflict-resolution.md 2>/dev/null || true`) --> Read protocol: `${PG_PROTOCOLS}/conflict-resolution.md` (use the `read_file` tool before continuing). <!-- inline shell (was: !`cat .production-grade.yaml 2>/dev/null || echo "No config — using defaults"`) --> Run shell command before continuing: ``cat .production-grade.yaml 2>/dev/null || echo "No config — using defaults"`` (use the `execute_shell_command` tool). **Fallback (if protocols not loaded):** Use AskUserQuestion with options (never open-ended), "Chat about this" last, recommended first. Work continuously. Print progress constantly. Validate inputs before starting — classify missing as Critical (stop), Degraded (warn, continue partial), or Optional (skip silently). Use parallel tool calls for independent reads. Use smart_outline before full Read. ## Progress Output Follow `Claude-Production-Grade-Suite/.protocols/visual-identity.md`. Print structured progress throughout execution. **Skill header** (print on start): ``` ━━━ Skill Maker ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` **Phase progress** (print during execution): ``` [1/3] Pattern Analysis ✓ {N} recurring patterns identified ⧖ analyzing workflow structure... ○ skill generation ○ installation [2/3] Skill Generation ✓ {N} custom skills drafted ⧖ writing SKILL.md files... ○ installation [3/3] Installation ✓ {N} skills installed to .claude/skills/ ``` **Completion summary** (print on finish — MUST include concrete numbers): ``` ✓ Skill Maker {N} project-specific skills created ⏱ Xm Ys ``` ## Overview End-to-end skill and plugin creation pipeline. Interviews the user on what the skill should do, writes the SKILL.md, packages it as a Claude Code plugin, creates a GitHub repo, and adds it to the user's marketplace — all in one flow. ## Config Paths Read `.production-grade.yaml` at startup if available. Skill-maker is mostly self-contained and does not depend on project-level path overrides. ## When to Use - User asks to create a new skill or plugin - User describes a reusable workflow that should be a skill - User says "make a skill", "build a plugin", "I need a skill for..." - NOT for: editing existing skills (just edit the file directly) ## Process Flow ```dot digraph skill_maker { rankdir=TB; "Skill idea received" [shape=doublecircle]; "Phase 1: Interview" [shape=box]; "Phase 2: Write SKILL.md" [shape=box]; "User approves?" [shape=diamond]; "Phase 3: Package as plugin" [shape=box]; "Phase 4: Create repo & push" [shape=box]; "Phase 5: Add to marketplace" [shape=box]; "Done" [shape=doublecircle]; "Skill idea received" -> "Phase 1: Interview"; "Phase 1: Interview" -> "Phase 2: Write SKILL.md"; "Phase 2: Write SKILL.md" -> "User approves?"; "User approves?" -> "Phase 2: Write SKILL.md" [label="revise"]; "User approves?" -> "Phase 3: Package as plugin" [label="approved"]; "Phase 3: Package as plugin" -> "Phase 4: Create repo & push"; "Phase 4: Create repo & push" -> "Phase 5: Add to marketplace"; "Phase 5: Add to marketplace" -> "Done"; } ``` ## Phase 1: Interview (Quick) **Engagement mode determines interview depth:** - **Express**: Infer all answers from the project context and agent prompts. Skip interview entirely. Report inferences. - **Standard**: Ask 1-2 key questions (purpose + trigger conditions). Auto-resolve the rest. - **Thorough/Meticulous**: Ask 3-4 questions using AskUserQuestion, one at a time: 1. **What does this skill do?** — Core purpose in one sentence 2. **When should it trigger?** — Specific words, patterns, or situations 3. **What's the workflow?** — Steps the skill should follow (linear, loop, decision tree?) 4. **Skill type?** — Options: Technique (steps to follow), Pattern (mental model), Reference (docs/API guide), Workflow (multi-phase process) ## Phase 2: Write SKILL.md Follow these rules from the writing-skills methodology: **Frontmatter:** - `name`: kebab-case, letters/numbers/hyphens only - `description`: Start with "Use when...", max 500 chars, triggering conditions only — NEVER summarize the workflow **Structure:** ```markdown --- name: skill-name description: Use when [triggering conditions] --- # Skill Name ## Overview Core principle in 1-2 sentences. ## When to Use Bullet list with symptoms and use cases. ## Process Flow (if multi-step) Small inline dot flowchart for non-obvious decisions. ## [Core Content] Steps, patterns, or reference material. ## Common Mistakes Table of mistake -> fix pairs. ``` **Quality rules:** - One excellent example beats many mediocre ones - Flowcharts ONLY for non-obvious decision points - Keep under 500 words for standard skills - Use active voice, verb-first naming - Include keywords for discoverability (error messages, symptoms, tool names) **Skill review (mode-aware):** Express — proceed to packaging, report skill summary. Standard — present brief summary for approval. Thorough/Meticulous — present full SKILL.md for detailed review via AskUserQuestion. ## Phase 3: Package as Plugin Create the plugin directory structure: ``` <skill-name>-plugin/ ├── .claude-plugin/ │ └── plugin.json ├── skills/ │ └── <skill-name>/ │ └── SKILL.md └── README.md ``` **plugin.json template:** ```json { "name": "<skill-name>", "description": "<one-line description>", "version": "1.0.0", "author": { "name": "<from git config or ask>" }, "license": "MIT", "keywords": ["<relevant>", "<tags>"] } ``` **README.md template:** ```markdown # <Skill Name> Plugin for Claude Code <description> ## Installation ### Via Marketplace /plugin marketplace add nagisanzenin/claude-code-plugins /plugin install <skill-name>@nagisanzenin ### Load Directly claude --plugin-dir /path/to/<skill-name>-plugin ## Usage <trigger description and examples> ## License MIT ``` ## Phase 4: Create Repo & Push 1. `git init` in the plugin directory 2. `git add -A && git commit -m "Initial release: <skill-name> plugin v1.0.0"` 3. `gh repo create <skill-name>-plugin --public --source . --push` 4. If `gh` auth fails, guide user through `gh auth login` ## Phase 5: Add to Marketplace 1. Read the user's marketplace repo (default: `nagisanzenin/claude-code-plugins`) 2. Clone or locate the marketplace locally 3. Add new plugin entry to `.claude-plugin/marketplace.json`: ```json { "name": "<skill-name>", "source": { "source": "github", "repo": "nagisanzenin/<skill-name>-plugin" }, "description": "<description>", "version": "1.0.0" } ``` 4. Update README.md plugin table 5. Commit and push marketplace repo 6. Report final install command: `/plugin install <skill-name>@nagisanzenin` ## Marketplace Config **Default marketplace repo:** `nagisanzenin/claude-code-plugins` **Default marketplace local path:** `~/nagisanzenin-plugins` **Default plugin location:** `~/<skill-name>-plugin` If the user has a different marketplace, ask which one to use. ## Common Mistakes | Mistake | Fix | |---------|-----| | Description summarizes workflow | Description = triggering conditions ONLY. "Use when..." | | Special chars in name | Letters, numbers, hyphens only. No parentheses. | | Skill too verbose (500+ words) | Cut ruthlessly. One example, not five. | | Missing keywords for discovery | Add error messages, symptoms, tool names in the content | | Forgetting to update marketplace | Always add to marketplace.json AND push | | Plugin files inside .claude-plugin/ | Only plugin.json goes in .claude-plugin/. Skills at root level. | <!-- production-grade v0.1 port adaptation notes --> > This skill body has been adapted for QwenPaw. Differences vs the upstream > Claude Code plugin to be aware of: > > - **No `AskUserQuestion` tool.** When this skill says to surface a decision, > render numbered options as plain Markdown and ask the user to type the > option name. Parse free-text replies leniently. > - **No `Skill` tool.** Phase transitions happen in-line: read the next > sub-skill body via `read_file` from the workspace `skills/` dir. > - **No subagent spawn.** v0.1 is a single-agent flow. If the methodology > says "delegate to specialist X", invoke X by reading its `SKILL.md` from > `skills/<name>/SKILL.md` and following its instructions yourself. > - **No `TaskCreate`/`TaskList`.** Track progress by writing receipts to > `Claude-Production-Grade-Suite/.orchestrator/receipts/<task>-<role>.json` > and emitting a one-line status update in chat after each phase. > - **`WebSearch` is `tavily_search`.** Requires `TAVILY_API_KEY`. If unset, > skip the Freshness Protocol and note it.