# Skills Builder

> Build, review, and improve any Claude skill interactively. Use when user says "build a skill", "create a skill", "review my skill", "improve this skill", "I need a skill for", "skill template", or "help me write a skill". Do NOT use when user wants to build an actual app, website, or API — only when they want to create a SKILL for Claude.

- Skill: `princekrz/skills-builder` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add princekrz/skills-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/princekrz/skills-builder/raw
- Safety review: WARNING (external: skill-scanner WARNING, skillspector FAIL)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: princekrz (https://skillmd.com/u/princekrz)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/princekrz/skills-builder

---


# Universal Skills Builder

Build ANY type of Claude skill — from simple reference guides to complex multi-MCP workflow automations, visual generators, and everything in between. Use ultrathink for complex skill generation.

## Critical Rules

- **Iron Law (TDD):** NO SKILL WITHOUT A FAILING TEST FIRST. Run a baseline scenario WITHOUT the skill present, capture verbatim failures, then write the skill. Applies to NEW skills AND EDITS. See [references/source-patterns-2026.md](references/source-patterns-2026.md) §1.
- ALWAYS ask the user clarifying questions before generating, but **CAP at 2-3 questions** for action skills (mattpocock pattern) — start exploring after.
- For interview skills: ONE question per message, never batch.
- If you don't know enough about a domain, use WebSearch to research it first.
- Generate complete, production-ready skills — not stubs or placeholders. **Minimal is fine** — a 50-word skill that does one thing well beats a 500-line skill (mattpocock `grill-me` is 4 lines).
- Validate every generated skill: `python ${CLAUDE_SKILL_DIR}/scripts/validate-skill.py <path>`
- Cross-skill conflict detection: `python ${CLAUDE_SKILL_DIR}/scripts/validate-skill.py --check-conflicts <path>` (gap #3)
- Security-scan every generated skill: `python ${CLAUDE_SKILL_DIR}/scripts/security-scan.py <path>`
- Scaffold new skills: `bash ${CLAUDE_SKILL_DIR}/scripts/scaffold-skill.sh <name> [target-dir] [--style minimal|gstack|mattpocock|discipline|default]`
- Phase checkpoint (compaction-safe): `bash ${CLAUDE_SKILL_DIR}/scripts/state-checkpoint.sh <skill-dir> set <phase>` (gap #2)
- Snapshot before edit: `bash ${CLAUDE_SKILL_DIR}/scripts/snapshot.sh <skill-dir> [tag]` (gap #6)
- Restore: `bash ${CLAUDE_SKILL_DIR}/scripts/restore.sh <skill-dir> --latest` (gap #6)
- Live RED test: `bash ${CLAUDE_SKILL_DIR}/scripts/red-test.sh <skill-dir> <scenario.txt>` (gap #1)
- Hard-gate hook (one-time install per env): copy `${CLAUDE_SKILL_DIR}/hooks/settings-snippet.json` into `~/.claude/settings.json` to enforce "no Write to SKILL.md without `<dir>.plan.approved` marker" (gap #5)
- Skills work across Claude.ai, Claude Code, and API. Build for portability.
- Keep generated SKILL.md bodies under 500 lines (MAX, not target). Move detail into `references/`.
- Front-load the most important instructions in the first 5,000 tokens (compaction keeps only that much).
- **Description = trigger conditions ONLY, never workflow summary.** Workflow in description = Claude follows the description and skips the body. See [references/source-patterns-2026.md](references/source-patterns-2026.md) §2.
- **Self-Containment Promise:** skills-builder runs end-to-end on its own bundled scripts and references. NEVER invoke another skill (`grill-me`, `superpowers:brainstorming`, `superpowers:writing-plans`, `office-hours`, etc.) at runtime. All grill / brainstorm / plan / TDD logic is owned inline + in `references/built-in-*.md`. Inspiration is credited in [references/source-patterns-2026.md](references/source-patterns-2026.md) but NEVER chained.

## Security Rules (Apply to EVERY Skill You Build)

- **No hardcoded secrets** — NEVER put API keys, tokens, passwords in any skill file. Use `$ENV_VAR`.
- **No shell injection** — NEVER pass `$ARGUMENTS` into dynamic context (exclamation-backtick) syntax. Use `sanitize.py` to validate input first.
- **Least privilege tools** — NEVER use `allowed-tools: "Bash(*)"`. Scope to specific commands. Review if granting 5+ tool patterns.
- **Side-effect guard** — Skills that deploy, send, delete, or modify external state MUST set `disable-model-invocation: true`.
- **Script safety** — Bundled scripts MUST use `subprocess.run([...])` not `os.system()` or `shell=True`. No network access unless explicitly required. No `pip install` from untrusted sources.
- **Path safety** — Validate file paths with `python ${CLAUDE_SKILL_DIR}/scripts/sanitize.py --validate-path <path>`. Never write to system directories.
- **Output safety** — Skills generating HTML MUST escape user content. Use `python ${CLAUDE_SKILL_DIR}/scripts/sanitize.py --html-escape <content>`.
- **Rate limiting** — Skills calling MCP/APIs in loops MUST include batch limits and delays. Never make unbounded API calls.
- **Isolation** — Use `context: fork` with `agent: Explore` for processing untrusted input (read-only sandbox).
- **Rollback** — Destructive skills MUST include rollback instructions. See [references/rollback-patterns.md](references/rollback-patterns.md).
- **Team trust** — Project skills run for ALL team members. Recommend CODEOWNERS review for `.claude/skills/` changes.
- See [references/security-guide.md](references/security-guide.md) for the full threat model, checklist, and enterprise controls.

## Instructions

### Step 0: Determine Intent

| User wants to... | Go to |
|---|---|
| Build a new skill from scratch | Workflow A |
| Build a skill from existing code/repo | Workflow B |
| Review/audit an existing skill | Workflow C |
| Fix or improve an existing skill | Workflow D |
| Convert a repetitive workflow into a skill | Workflow E |
| Find, download, and install an existing skill from GitHub | Workflow F |

If unclear, ask: "Do you want to build a new skill, find an existing one, review one, or improve one?"

---

### Workflow A: Build a New Skill (Interactive)

#### Phase 0: RED — Baseline Test (NEW, mandatory)

Before writing the skill, run a pressure scenario WITHOUT it present. Document verbatim:
- What the agent did
- What rationalizations it used
- Which pressures triggered violations

This is the failing test. If you can't articulate what failure looks like, you don't know what the skill should fix. See [references/source-patterns-2026.md](references/source-patterns-2026.md) §1.

For new domains where there's no existing failure to baseline (e.g. "build me a skill for FastAPI docs"), skip this phase but flag the skill as untested in the final report.

#### Phase 1: Discovery

**Mode selection — ask the user FIRST:**
> "Quick discovery (4-6 questions) or full grill (relentless one-by-one until every decision branch resolved)? Default: quick."

| Mode | When to use | Style |
|------|-------------|-------|
| `quick` | Skill purpose is clear, simple scope | Conversational, ~5 Qs total |
| `grill` | Complex skill, multiple modes, fuzzy requirements, user said "grill", "stress-test", "make sure this is right" | One Q per message, walk every branch, propose recommended answer for each |

---

**Quick mode:**

Have a conversation — do NOT dump all questions at once.

**First, ask these two:**
1. What should the skill do? (Get a clear outcome)
2. What would someone say to trigger it? (Get 2-3 natural phrases)

**Then, based on answers, follow up with:**
- Who will use it? (Just you / team / public)
- Does it need external tools or MCP servers?
- Should it be manual-only (`/skill-name`) or auto-invoked by Claude?
- Does it take arguments? (e.g., `/deploy staging`, `/fix-issue 123`)

If the description is vague or you're unfamiliar with the domain, use WebSearch to research before proceeding.

---

**Grill mode (skills-builder built-in relentless interview):**

Owned by skills-builder. Full method in [references/built-in-grill-method.md](references/built-in-grill-method.md). Do NOT delegate to any other skill.

Walk every branch of the decision tree. ONE question per message. Wait for answer. Provide a recommended answer with each question.

**Decision tree to walk (in order):**

1. **Outcome** — what artifact does this skill produce? Concrete example?
2. **Triggers** — list 5+ phrases users would actually say. Reject jargon-only.
3. **Mode** — manual-only (`/skill`), auto-invoked by Claude, or both?
4. **Side effects** — does it deploy/send/delete/modify external state?
   - If yes → MUST use `disable-model-invocation: true` and rollback plan
5. **Arguments** — none, positional, or `--flag`-style? Variadic? Optional?
6. **External deps** — MCP servers? CLI tools? APIs? Auth?
7. **Failure modes** — top 3 ways it could go wrong. How to handle each?
8. **Anti-pattern** — what's the #1 way someone WILL misuse this?
9. **Skill type** — discipline / technique / pattern / reference / interview / pipeline-stage?
10. **Style** — default / minimal / gstack-specialist / mattpocock-XML / discipline?
11. **Body length budget** — <150 words / <200 / <500 / >500 (split refs)?
12. **Chain** — what skill comes BEFORE this? AFTER? (`benefits-from`, "After Completion")
13. **Domain language** — does the project have `CONTEXT.md` / `docs/adr/`? If yes, what terms are load-bearing?
14. **Test plan** — what's the RED scenario (run the failure WITHOUT skill present)?
15. **Audience** — just you / team / public marketplace?
16. **Permissions** — minimum tool set? Any `Bash(*)` warnings?

Rules during grill:
- ONE question per message. Never batch.
- Always propose a recommended answer ("My recommendation: X. Sound right?")
- If user answer is vague, push back: "Be more specific. Give me an example."
- If a question can be answered by exploring the codebase, explore the codebase instead of asking the user.
- Stop only when all 16 branches resolved OR user says "ship it".

After grill, the rest of Workflow A proceeds as normal — but with much higher resolution input.

#### Phase 1.5: Brainstorm (self-contained — built-in brainstorm method)

Owned by skills-builder. Full method in [references/built-in-brainstorm-method.md](references/built-in-brainstorm-method.md). Do NOT delegate to any other skill.

Before settling on a design, explore intent and alternatives. Run if ANY of these are true:
- Skill scope spans 2+ workflows or modes
- User said "brainstorm", "think through", "options", "approach"
- Same problem could plausibly be solved by extending an existing skill instead

**Three forcing prompts (answer all before continuing):**

1. **Intent** — what problem is this skill solving for the user, in their voice? Not "build X" but "I waste 20 min every release figuring out which tests to run."
2. **Alternatives** — list 3+ ways to solve it. New skill / extend existing skill / hook / settings change / docs entry. Why is "new skill" the right shape?
3. **Design surface** — name the inputs, outputs, side effects, and the smallest possible interface. If the interface needs >5 args, the skill is doing too much.

If any answer is fuzzy, loop back to Phase 1 grill on that branch.

**Skip Phase 1.5** when: skill is trivial (minimal-style 4-line skill), user explicitly says "skip brainstorm", or scope is one verb / one outcome.

#### Phase 1.7: Plan (self-contained — built-in plan method)

Write a plan artifact BEFORE generating code. Plan = `~/.claude/skills/<name>.plan.md` (or `.claude/skills/<name>.plan.md` for project skills).

This phase is owned by skills-builder. Full method in [references/built-in-plan-method.md](references/built-in-plan-method.md). Do NOT delegate to any other skill.

**Plan template:**

```markdown
# Plan: <skill-name>

## Goal
[One sentence — what the skill produces, for whom.]

## Non-goals
- [Out of scope 1]
- [Out of scope 2]

## Inputs / Outputs
- Inputs: [args, files, MCP, env vars]
- Outputs: [files written, side effects, return artifact]

## Phase checklist
- [ ] Frontmatter (name, description, allowed-tools, paths)
- [ ] Body skeleton (style: default | minimal | gstack | mattpocock | discipline)
- [ ] Scripts (list each + purpose)
- [ ] References (list each + purpose)
- [ ] Assets (list each)
- [ ] RED baseline test scenario captured
- [ ] Security review (10 domains)
- [ ] Pro Quality Gate score ≥ 14/18
- [ ] Test plan (triggering + functional + security)

## Review checkpoints
1. After frontmatter → user approves description + triggers
2. After body skeleton → user approves structure
3. Before security review → user approves complete content
4. After validation → user approves install location

## Risks
- [Risk 1 + mitigation]
- [Risk 2 + mitigation]

## Out-of-band tools / MCP needed
- [list]

## Done when
- [Acceptance criterion 1]
- [Acceptance criterion 2]
```

**Rules:**
- Write the plan to disk. NOT just in conversation. Survives compaction.
- Present plan to user. Get explicit approval. Quote: "Approve plan? (yes/edit)".
- Edits trigger re-write — do NOT just acknowledge verbally and proceed.
- Plan checkpoints become hard gates in Phase 6 generation.

**Skip Phase 1.7** only when: minimal-style skill (single instruction, no scripts/references) AND user opts out explicitly.

#### Phase 2: Identify Type and Pattern

Match the user's need to a skill type and architectural pattern. Consult these references:
- For **skill types** (web, app, API, DevOps, data, docs, security, MCP, etc.): see [references/skill-type-catalog.md](references/skill-type-catalog.md)
- For **architectural patterns** (pure instructions, scripts, templates, visual output, sequential, multi-MCP, iterative, subagent fork, etc.): see [references/skill-patterns.md](references/skill-patterns.md)
- For **ready-to-copy blueprints**: see [references/skill-type-blueprints.md](references/skill-type-blueprints.md)

Tell the user which type and pattern you recommend and why. Get approval before continuing.

#### Phase 3: Generate Frontmatter

Build the YAML frontmatter. Consult [references/frontmatter-reference.md](references/frontmatter-reference.md) for all fields, rules, and examples.

**Key rules (always apply these):**
- `---` delimiters on both sides
- `name`: kebab-case, max 64 chars, no spaces/capitals, no "claude"/"anthropic" prefix
- `description`: **TRIGGER CONDITIONS ONLY — never summarize the workflow.** Start with "Use when...". Front-load symptoms, error messages, situations, file types, jargon. Workflow summaries become a shortcut Claude takes INSTEAD of reading the body (proven via testing — see [references/source-patterns-2026.md](references/source-patterns-2026.md) §2). Make it slightly pushy on triggers — Claude under-triggers by default.
- Add `disable-model-invocation: true` for skills with side effects (deploy, send, delete)
- Add `paths:` for file-type-specific skills (e.g., `"**/*.py"`)
- Add `argument-hint:` if the skill takes input
- No XML angle brackets anywhere in frontmatter

**Description formula (updated 2026-04 — see [references/source-patterns-2026.md](references/source-patterns-2026.md) §2):**
```
Use when [trigger phrase 1], [trigger phrase 2], or [symptom/jargon].
[One short capability sentence — what it produces, no workflow steps.]
[Optional: Do NOT use for X.]
```

**Anti-pattern — workflow summary in description:**
```yaml
# WRONG — summary becomes a shortcut Claude takes instead of reading the body
description: Use for TDD - write test first, watch fail, write minimal code, refactor

# RIGHT — triggers + outcome only
description: Use when implementing any feature or bugfix, before writing implementation code
```

Present the frontmatter to the user for approval before continuing.

#### Phase 4: Write the Skill Body (Superpowers Pattern)

ALL skills MUST follow the superpowers structure pattern. This is non-negotiable.

**CRITICAL: Before writing any skill body, read [references/superpowers-writing-guide.md](references/superpowers-writing-guide.md).** It contains:
- Category-specific templates (interview, automation, analysis, process, workflow)
- 15 golden rules from superpowers + mattpocock + gstack (84k-star repo)
- Writing techniques: hard gates, confrontation patterns, stage-aware routing, push patterns
- gstack pro patterns: parameterized arguments, allowed-tools scoping, cross-skill integration, trend output, conservative updates, mode detection

Match the template for the skill's category. Apply gstack patterns for professional-grade skills.

```markdown
# Skill Name

[1-2 sentence overview of what the skill does and when it's used.]

<HARD-GATE>
[Non-negotiable constraint — what must NOT happen before X is done.
Example: "Do NOT write code until the user approves the design."]
</HARD-GATE>

## Anti-Pattern: "[Common Mistake Name]"
[Call out the #1 way people misuse this skill and why it fails.]

## Checklist

You MUST create a task for each of these items and complete them in order:

1. **Step name** — what to do
2. **Step name** — what to do
3. **Step name** — what to do
[...]

## Process Flow

` ` `dot
digraph skill_name {
    "Step 1" [shape=box];
    "Decision?" [shape=diamond];
    "Step 2" [shape=box];
    "Terminal state" [shape=doublecircle];
    
    "Step 1" -> "Decision?";
    "Decision?" -> "Step 2" [label="yes"];
    "Decision?" -> "Step 1" [label="no, revise"];
    "Step 2" -> "Terminal state";
}
` ` `

## The Process

**[Phase name]:**
- Detailed instructions for this phase
- Specific actions, not vague language
- One question/action at a time

**[Phase name]:**
- Next phase details
[...]

## Key Principles

- **Principle 1** — explanation
- **Principle 2** — explanation
- **Principle 3** — explanation

## After Completion

[What skill to invoke next, or what output to produce.]
[Skills MUST chain explicitly: "Invoke the X skill to proceed."]
```

**Pattern rules (enforce on every skill):**
- **Hard gates first** — `<HARD-GATE>` tags for non-negotiable constraints at the top
- **Anti-patterns** — call out the #1 misuse explicitly, right after the gate
- **Numbered checklist** — ordered steps Claude must track as tasks
- **Process flow diagram** — dot notation showing decision points and terminal states
- **One question per message** — skills that interact with user ask ONE thing at a time
- **Explicit transitions** — every skill names which skill comes next
- **Pushy descriptions** — descriptions front-load action verbs, include "You MUST" or "Use when" phrasing
- Be specific: `python scripts/build.py --target prod` not "build the thing"
- Put critical instructions at the very top — first 5,000 tokens survive compaction
- Use `$ARGUMENTS` / `$0` / `$1` for user input
- Use `${CLAUDE_SKILL_DIR}` to reference bundled files
- Reference bundled files explicitly: "See [reference.md](reference.md)"
- Keep under 500 lines — move details to `references/`

**Side-effect skills** (deploy, send, delete): set `disable-model-invocation: true`, add confirmation steps, include rollback instructions per [references/rollback-patterns.md](references/rollback-patterns.md).

**Visual output skills** (HTML, charts): bundle a Python/JS script, use `webbrowser.open()`, keep output self-contained. ALWAYS escape user content with `sanitize.py --html-escape` before embedding in HTML to prevent XSS.

**MCP skills**: name exact tools (`Call MCP tool: create_issue`), handle disconnections, verify between calls. Add rate limiting when calling MCP tools in loops — max N items per batch, delay between calls, require user confirmation for large batches.

**Skills taking $ARGUMENTS**: validate input with `python ${CLAUDE_SKILL_DIR}/scripts/sanitize.py --validate-path` for file paths, `--sanitize-args` for shell arguments, `--validate-url` for URLs. NEVER pass raw `$ARGUMENTS` to shell commands.

**Skills for teams** (project-level): note in the skill's instructions that it runs for all team members. Recommend adding `.claude/skills/` to CODEOWNERS. Use `context: fork` with `agent: Explore` for processing untrusted input in a read-only sandbox.

#### Phase 5: Plan File Structure (Superpowers Layout)

**Single skill:**
```
skill-name/
├── SKILL.md              # Required — main instructions (under 500 lines)
├── scripts/              # Optional — deterministic logic
├── references/           # Optional — loaded on demand by Claude
└── assets/               # Optional — templates, static files
```

**Plugin with multiple sub-skills (superpowers pattern):**
```
plugin-name/
├── SKILL.md              # Plugin entry — overview + skill index
├── references/           # Shared knowledge across all sub-skills
│   ├── patterns.md
│   └── templates.md
├── skills/               # Individual sub-skills
│   ├── skill-one/
│   │   └── SKILL.md      # Registers as plugin-name:skill-one
│   └── skill-two/
│       └── SKILL.md      # Registers as plugin-name:skill-two
├── hooks/                # Optional — PreToolUse/PostToolUse hooks
├── agents/               # Optional — subagent definitions
├── scripts/              # Optional — shared scripts
└── plugin.json           # Optional — for marketplace publishing
```

**When to use plugin structure:** If building 3+ related skills that share references or chain together, use plugin layout. Sub-skills auto-register as `plugin-name:skill-name`.

Rules: `SKILL.md` exact spelling, folder = kebab-case matching `name`, no `README.md` inside, scripts use stdlib only when possible.

Or run: `bash ${CLAUDE_SKILL_DIR}/scripts/scaffold-skill.sh <name> [target-dir]`

#### Phase 6: Generate Everything

After user approves:
1. Create folder structure (or use scaffold script)
2. Write complete `SKILL.md`
3. Write all scripts (make executable with `chmod +x`)
4. Write all references and assets
5. Validate: `python ${CLAUDE_SKILL_DIR}/scripts/validate-skill.py <path>`
6. Provide installation instructions:

| Scope | Path |
|---|---|
| Personal (all projects) | `~/.claude/skills/<name>/SKILL.md` |
| Project-only | `.claude/skills/<name>/SKILL.md` |
| Plugin | `<plugin>/skills/<name>/SKILL.md` |
| Managed (org-wide) | Via managed settings |
| Monorepo package | `packages/<pkg>/.claude/skills/<name>/SKILL.md` |
| Claude.ai | Zip folder → Settings → Skills → Upload |
| API | `/v1/skills` endpoint with `container.skills` |

#### Phase 7: Security Review

Run the automated security scanner:
```
python ${CLAUDE_SKILL_DIR}/scripts/security-scan.py <path>
```

Then manually verify all 10 security domains:

| # | Check | How |
|---|---|---|
| 1 | **No secrets** | No API keys/tokens/passwords in any file |
| 2 | **Input validated** | `$ARGUMENTS` validated with `sanitize.py` before use, never in shell |
| 3 | **Output escaped** | HTML skills escape user content (no XSS) |
| 4 | **No untrusted deps** | No `pip install`/`npm install` from unknown sources, no `curl\|sh` |
| 5 | **Least privilege** | `allowed-tools` scoped to specific commands, not `Bash(*)` |
| 6 | **Rollback included** | Destructive skills have rollback instructions |
| 7 | **Isolation used** | `context: fork` for untrusted input processing |
| 8 | **Side-effects guarded** | `disable-model-invocation: true` for deploy/send/delete skills |
| 9 | **Team-safe** | Project skills don't grant excessive permissions to all devs |
| 10 | **Rate-limited** | MCP/API loops have batch limits and delays |

Fix ALL findings before proceeding. See [references/security-guide.md](references/security-guide.md).

#### Phase 8: Pro Quality Gate (run before declaring skill complete)

Score every generated skill against these 18 checks. Minimum 14/18 to ship.

| # | Check | Pass? |
|---|-------|-------|
| 1 | Has `<HARD-GATE>` with clear blocking constraint (discipline skills only) | |
| 2 | Has named anti-pattern section | |
| 3 | Has numbered checklist (tasks Claude tracks) | |
| 4 | Description = TRIGGER CONDITIONS only — no workflow summary | |
| 5 | Critical rules in first 5,000 tokens | |
| 6 | One question per message for interview skills; max 2-3 questions for action skills | |
| 7 | Explicit skill chaining ("Invoke X skill next") | |
| 8 | Stage-aware routing (skips irrelevant steps based on context) | |
| 9 | Confrontation/push patterns for weak answers (interview skills) | |
| 10 | Tables for decisions, not prose | |
| 11 | Good/Bad paired examples where applicable | |
| 12 | ALWAYS/NEVER list for content modification skills | |
| 13 | `allowed-tools` scoped (not `Bash(*)`) | |
| 14 | Arguments support if skill has modes (`/skill arg`) | |
| 15 | Key Principles section at bottom (3-5 rules) | |
| 16 | **NEW**: Baseline RED test run WITHOUT the skill — failures documented | |
| 17 | **NEW**: Word count in budget (`wc -w SKILL.md`: <150 for getting-started, <200 frequently-loaded, <500 other) | |
| 18 | **NEW**: Domain-language aware — reads `CONTEXT.md` / `UBIQUITOUS_LANGUAGE.md` / `docs/adr/` if present, uses project terms in output, no file/line citations | |

**Score < 14:** Fix before shipping. Show user which checks failed.
**Score 14-16:** Ship with notes on what could improve.
**Score 17-18:** Perfect — ship it.

See [references/source-patterns-2026.md](references/source-patterns-2026.md) for the full rationale behind checks 16-18 (TDD-for-skills, token efficiency, domain awareness — sourced from superpowers, mattpocock, gstack).

#### Phase 9: Test Plan

```
TRIGGERING:
  Should trigger: ["exact phrase", "paraphrased", "domain jargon"]
  Should NOT trigger: ["unrelated", "similar but out-of-scope"]

FUNCTIONAL:
  Test 1 (happy path): Given X → When Y → Then Z
  Test 2 (edge case): Given unusual input → graceful handling

SECURITY:
  Test: Invoke with malicious $ARGUMENTS (shell metacharacters, path traversal)
  Expected: Skill handles gracefully, no code execution, no file access outside scope

VERIFY:
  Ask Claude: "When would you use the [name] skill?"
  Invoke: /skill-name and check output
```

---

### Workflow B: Build Skill from Existing Code/Repo

When the user points to existing code, a repo, a script, or a URL:

#### Step 1: Explore the Source
- Read the code/files the user points to
- If it's a URL, fetch it with WebFetch
- If it's a repo, explore the structure with Glob/Grep
- Understand: what does this code do? What's the workflow?

#### Step 2: Extract the Pattern
- What steps does the process follow? (sequential, branching, iterative?)
- What's constant vs. what changes each run?
- What are the inputs, outputs, and side effects?
- What domain knowledge is embedded that Claude needs?

#### Step 3: Identify Variables
- What changes per use → these become `$ARGUMENTS` or `$0`, `$1`
- What's configurable → these go in the instructions as decision points
- What's hardcoded → these become the skill's embedded knowledge

#### Step 4: Research if Needed
Use WebSearch to understand frameworks, APIs, or domain conventions the skill needs.

#### Step 5: Build
Proceed to **Workflow A Phase 2** with the discovered information. Tell the user what you extracted and get confirmation before generating.

**Example flow:**
```
User: "Turn my deploy.sh into a skill"
→ Read deploy.sh
→ Extract: it runs tests, builds Docker image, pushes to ECR, updates ECS
→ Variables: environment ($0), image tag ($1)
→ Pattern: Sequential Workflow with side effects
→ Frontmatter: disable-model-invocation: true, argument-hint: "[env] [tag]"
→ Generate skill with the deploy steps as instructions
```

---

### Workflow C: Review/Audit an Existing Skill

First run automated checks:
```
python ${CLAUDE_SKILL_DIR}/scripts/validate-skill.py <path>
python ${CLAUDE_SKILL_DIR}/scripts/security-scan.py <path>
```

Then manually audit across 5 levels:

**Level 1 — Structure (Critical)**
- [ ] File named exactly `SKILL.md`, folder is kebab-case
- [ ] YAML `---` delimiters, no XML angle brackets
- [ ] `name` valid (lowercase, hyphens, max 64, no reserved prefix)

**Level 2 — Security (Critical)**
- [ ] No hardcoded secrets in any file (API keys, tokens, passwords, connection strings)
- [ ] No `$ARGUMENTS` in dynamic context (exclamation-backtick) — input validated with `sanitize.py` before use
- [ ] `allowed-tools` scoped to specific commands (never `Bash(*)`, review if 5+ patterns)
- [ ] `disable-model-invocation: true` on skills with side effects
- [ ] Scripts use `subprocess.run([...])` not `os.system()` or `shell=True`
- [ ] Scripts don't access network or env vars unless documented
- [ ] No credential files (.env, *.key) in the skill folder
- [ ] No `pip install`/`npm install` from untrusted sources, no `curl|sh`
- [ ] File write operations validate paths (no system directories)
- [ ] HTML output escapes user content (no XSS)
- [ ] MCP/API calls in loops have rate limits and batch caps
- [ ] `context: fork` considered for untrusted input processing
- [ ] Rollback instructions included for destructive operations
- [ ] Project skills safe for all team members (no excessive permissions)
- [ ] See [references/security-guide.md](references/security-guide.md) for full checklist

**Level 3 — Triggering (High)**
- [ ] Description has WHAT + WHEN with specific trigger phrases
- [ ] First 250 chars contain the key use case (truncated in listings)
- [ ] Slightly "pushy" (Claude under-triggers by default)
- [ ] Negative triggers if needed ("Do NOT use for...")
- [ ] `paths:` set for file-type-specific skills

**Level 4 — Instructions (Medium)**
- [ ] Critical rules in first 5,000 tokens (survives compaction)
- [ ] Specific and actionable — no vague language
- [ ] Examples provided (2+), error handling included
- [ ] Under 500 lines, heavy content in `references/`
- [ ] `$ARGUMENTS` used correctly if skill takes input
- [ ] Bundled files referenced explicitly

**Level 5 — Pro Patterns (High — from superpowers/gstack)**
- [ ] Has `<HARD-GATE>` blocking constraint at top
- [ ] Has named anti-pattern section ("Anti-Pattern: [Name]")
- [ ] Has numbered checklist (tasks Claude tracks in order)
- [ ] Has Key Principles section at bottom (3-5 rules)
- [ ] Stage-aware routing (detects context, skips irrelevant steps)
- [ ] Confrontation/push patterns for interview questions
- [ ] Tables for decisions (not prose paragraphs)
- [ ] Good/Bad paired examples where applicable
- [ ] ALWAYS/NEVER lists for content modification
- [ ] Arguments support if skill has modes
- [ ] Explicit skill chaining to next skill
- [ ] DOT process flow diagram for complex workflows
- [ ] `version` in frontmatter

**Level 6 — Advanced (Suggestions)**
- [ ] Progressive disclosure (frontmatter → body → references)
- [ ] Scripts for critical validations
- [ ] `allowed-tools` pre-approves relevant tools
- [ ] `context: fork` for heavy isolated tasks
- [ ] Performance notes / "ultrathink" for complex skills
- [ ] Cross-skill integration via `.context/` marker files
- [ ] Trend/comparison output with history persistence

Output: summary table with severity (Critical/High/Medium/Low) and specific fixes. Run Pro Quality Gate (Phase 8) scoring — report score out of 15.

---

### Workflow D: Improve a Skill from Feedback

| Symptom | Cause | Fix |
|---|---|---|
| Never triggers | Description too vague | Add trigger phrases, make pushier |
| Triggers on everything | Description too broad | Add "Do NOT use for...", set `paths:`, narrow scope |
| Instructions ignored | Critical rules buried | Move to top (first 5,000 tokens), use `## Critical` header |
| Inconsistent results | Ambiguous language | Replace with exact commands/scripts |
| Model seems "lazy" | No encouragement | Add Performance Notes, include "ultrathink" |
| Context bloat / slow | Body too large | Move to `references/`, keep under 500 lines |
| MCP calls fail | Wrong tool names | Verify exact MCP tool names, add connection checks |
| Stops working mid-chat | Compaction dropped it | Keep critical rules in first 5,000 tokens, re-invoke after compaction |
| Works in Claude.ai not Code | Platform difference | Check `compatibility`, verify tool availability |
| Too many skills conflict | Description budget exceeded | Set `SLASH_COMMAND_TOOL_CHAR_BUDGET` env var to raise the 8,000-char default |
| Feels amateur/shallow | Missing pro patterns | Run Pro Quality Gate (Phase 8) — add hard gates, anti-patterns, push patterns |
| Asks too many questions at once | No interaction discipline | Enforce ONE question per message, multiple choice preferred |
| User skips important steps | No hard gate | Add `<HARD-GATE>` blocking progression until prerequisite met |
| Same questions for all contexts | No stage routing | Add mode detection + context-based step skipping |
| Weak answers accepted | No confrontation | Add push patterns with specific rebuttals per question |

For each fix, provide before/after examples and new test cases. Run Pro Quality Gate scoring after improvements.

---

### Workflow E: Convert a Repetitive Workflow into a Skill

When the user says "I keep doing X manually" or "every time I need to...":

1. **Ask them to walk through it** — step by step, or paste their usual prompts
2. **Identify the pattern** — what's constant vs. what changes?
3. **Extract variables** — what changes becomes `$ARGUMENTS`
4. **Determine automation level** — scriptable (deterministic) vs. needs Claude's judgment?
5. **Build the skill** — proceed to Workflow A Phase 2

---

### Workflow F: Discover, Download & Install Existing Skills

When the user wants to find an existing skill rather than building from scratch. Requires `gh` CLI (check with `python ${CLAUDE_SKILL_DIR}/scripts/skill-store.py check-env`).

See [references/discovery-guide.md](references/discovery-guide.md) for full details and search strategies.

#### Phase 1: Understand Need

Ask the user:
1. **What capability do you need?** (e.g., "code review", "deploy to AWS", "generate docs")
2. **Do you have a specific repo/URL, or should we search?**

If they have a URL → skip to Phase 3 (preview).
If they describe a need → proceed to Phase 2 (search).

#### Phase 2: Search & Present

Run: `python ${CLAUDE_SKILL_DIR}/scripts/skill-store.py search "<user's description>"`

Present results as a table showing name, stars, trust level, repo. Ask which skill interests them. If no results found, offer to build from scratch via Workflow A.

#### Phase 3: Preview & Security Audit

Run: `python ${CLAUDE_SKILL_DIR}/scripts/skill-store.py preview <repo> --path <skill-path>`

This fetches the SKILL.md to a quarantine directory and runs both validate-skill.py and security-scan.py. Present to user:
- Skill name, description, trust level, stars
- Validation results (pass/fail)
- Security scan results (CRITICAL = blocked, HIGH = warning, clean = safe)

Ask: "Do you want to download the full skill?"

#### Phase 4: Download to Quarantine

Run: `python ${CLAUDE_SKILL_DIR}/scripts/skill-store.py download <repo> --path <skill-path>`

This downloads ALL files (SKILL.md, scripts/, references/, assets/) to `/tmp/skill-quarantine-<uuid>/`. Full security scan runs on everything. Present results.

If CRITICAL findings → recommend NOT installing, suggest alternatives.
If clean → proceed to Phase 5.

#### Phase 5: Customize

Ask: "Would you like to customize this skill before installing?"

If yes, offer changes:
- **Rename**: `python ${CLAUDE_SKILL_DIR}/scripts/skill-store.py customize <path> --name <new-name>`
- **Tighten tools**: `--remove-tool "Bash(*)"` or `--allowed-tools "Read Grep Glob"`
- **Update description**: `--description "My customized version for..."`
- **Edit instructions**: Read and Edit the quarantined SKILL.md directly for deeper changes

Re-validate after every change.

#### Phase 6: Install

Ask: "Install to personal (all projects) or project (this repo only)?"

Run: `python ${CLAUDE_SKILL_DIR}/scripts/skill-store.py install <quarantine-path> --scope <personal|project>`

This runs final validation + security scan, copies to target, and cleans quarantine. Provide:
- Install location
- How to test (invoke with `/skill-name`)
- How to remove (`skill-store.py uninstall <name>`)

---

## End-to-End Example

Here's a complete interaction showing how this skill builds another skill:

```
User: "Build me a skill for generating API documentation"

Phase 1 — Discovery:
  Claude asks: "What should the skill produce — OpenAPI specs, markdown docs, 
  or HTML reference pages? And what would you say to trigger it?"
  User: "Markdown docs from my code. I'd say 'document this API' or 'generate API docs'"
  Claude asks: "Does your API use a specific framework? And is this just for you or your team?"
  User: "FastAPI, just for me"

Phase 2 — Type & Pattern:
  Claude: "This is a Document Creation skill using the Scripts + Resources pattern.
  I'll have it analyze your FastAPI routes and generate markdown. Sound good?"
  User: "Yes"

Phase 3 — Frontmatter:
  ---
  name: api-docs
  description: Generate markdown API documentation from FastAPI code. Use when 
  user says "document this API", "generate API docs", or "create endpoint docs".
  allowed-tools: "Read Grep Write"
  argument-hint: "[path-to-api-routes]"
  ---
  User: "Looks good"

Phase 6 — Generated files:
  api-docs/
  ├── SKILL.md           (instructions for analyzing routes + generating docs)
  ├── scripts/
  │   └── extract-routes.py  (parses FastAPI decorators, extracts schemas)
  └── references/
      └── doc-template.md    (markdown template for the output)

Phase 7 — Test plan:
  Should trigger: "document this API", "generate API docs", "create endpoint reference"
  Should NOT trigger: "build an API", "fix this endpoint", "write a test"
```

## Troubleshooting

**"Could not find SKILL.md"** — File not named exactly `SKILL.md` (case-sensitive).

**"Invalid frontmatter"** — Missing `---` delimiters, unclosed quotes, or XML brackets.

**"Skill loads but does nothing"** — If using `context: fork`, the skill needs task instructions, not just guidelines.

**"Description too long in listings"** — Front-load key use case in first 250 characters.

**"Skill disappears mid-conversation"** — Compaction kept only first 5,000 tokens. Put critical rules at top. Re-invoke with `/skill-name` to restore.

**"Too many skills, descriptions cut short"** — Raise the budget: `export SLASH_COMMAND_TOOL_CHAR_BUDGET=16000`

**Stuck on unfamiliar domain** — Use WebSearch to research, check anthropics/skills repo for examples, start simple and iterate.

**"GitHub CLI (gh) not installed"** — Required for Workflow F. Install: https://cli.github.com then run `gh auth login`.

**"GitHub API rate limit hit"** — Wait 1 min for search (30/min) or use authenticated `gh` for 5000 req/hr.

**"CRITICAL security issues in downloaded skill"** — Installation blocked. Choose a different skill or fix issues manually in quarantine before installing.

**"No skills found for query"** — Try broader keywords, or search official repo: `skill-store.py search "repo:anthropics/skills"`.