Skill builder

skill-builder — the SkynetLabs skill mint-press

Goal: produce a SKILL.md a future session will actually auto-invoke and follow, matching the house style of the skills already in ~/.claude/skills/. Not a doc. A loadable procedure.

First thing to do (every run): triage CLAUDE.md vs Skill

Before writing anything, classify the request (lesson from claude-code-mastery.md):

• Facts that are ALWAYS true (deploy targets, credentials location, host quirks, client names, fixed conventions) → belongs in CLAUDE.md, NOT a skill. Say so and offer to append to the right CLAUDE.md instead. Stop.
• A procedure you'd otherwise re-paste / re-explain (a multi-step workflow with inputs and outputs) → this is a skill. Proceed.
• Mixed? Split: facts → CLAUDE.md, procedure → skill that references the facts.

Rule of thumb: "CLAUDE.md = facts always true; Skill = procedures you'd re-paste." A skill that's just a list of facts will bloat context for zero leverage.

Inputs to elicit

If the user already described the workflow (or said "turn what we just did into a skill"), MINE the conversation first — don't re-ask what you can infer. Then fill gaps with ONE batched AskUserQuestion. Capture all 7:

1. name — kebab-case, ≤ 3 words, verb-y if it's an action (cv-tailor, ghl-video-drip). Must be unique vs existing skills (glob to check).
2. one-line purpose — what it does + for whom, in one sentence.
3. trigger phrases — 5-9 literal phrases a user would type, INCLUDING the /name slash form. These drive auto-invocation — weak triggers = dead skill.
4. inputs — what the user must provide each run (a file? a URL? a JD? a topic?).
5. steps — the ordered procedure. The load-bearing part. Get the real steps, including the order-matters gotchas.
6. outputs — the artifact(s) produced + WHERE they're written (absolute path).
7. gotchas — the hard-won traps ("NVENC broken → libx264", "videoUrl in col 6 not col 5", "this host = manual ZIP not GitHub auto-deploy"). These are gold — bake every one in.

If the user is vague, ask for the steps before generating. Never invent a procedure.

House style (extracted from fanout-ship / upwork-proposal / code-audit-fanout)

Match this exactly:

Frontmatter

---
name: <kebab-case> # MUST equal the folder name
version: 1.0.0 # start here; bump on real change
description: | # pipe block, multi-paragraph
  <2-4 line prose blurb: what it does, the win, the mechanism>

  <optional second paragraph: who it's tuned for / distilled-from receipt>

  Trigger when user says: "<phrase>", "<phrase>", "/<name>", ... (5-9 literal)

  Auto-trigger heuristic: <one concrete condition> (optional but preferred)
license: MIT
compatibility: claude-code
allowed-tools: # ONLY tools the steps actually use — least privilege
  - Read
  - Write
  - Edit
  - ...
---

The description is the single most important field — it's all a future session sees when deciding whether to load the skill. Pack it with literal trigger phrases.

Body sections (use the ones that fit; this is the menu, not a mandate)

• # <name> + one-line goal restatement
• ## When to use — USE when ALL true / SKIP when (bullet lists)
• ## Inputs — what the user supplies; what to ask if missing
• ## The N-step recipe or ## Workflow — numbered, runnable, with code blocks
• ## Templates — paste-and-go blocks (orchestrator prompt, output format)
• ## Output format — the exact structure to emit
• ## Files — list of helper files in the skill folder (only if they exist)
• ## Failure modes + fixes — a | Failure | Cause | Fix | table
• ## Anti-patterns — ❌ bullets
• ## Quality checklist — [ ] items to self-verify before delivering
• ## Cost model — when worth it / when to skip (for heavy/parallel skills)

Density: terse, imperative, concrete numbers and real paths. No filler, no "this powerful skill will help you". Arrows (→) for flows. Receipts where they exist ("distilled from batch7 2026-05-30").

The recipe

1. Triage (CLAUDE.md vs Skill)

Per section above. If facts-only → redirect to CLAUDE.md and stop.

2. Elicit the 7 inputs

Mine the conversation, then one batched AskUserQuestion for gaps.

3. Check name is free

Glob: ~/.claude/skills/<name>/SKILL.md

If it exists → confirm overwrite or pick a new name. Also glob **/<name>/SKILL.md in case it's nested under a plugin pack.

4. Generate the SKILL.md

Write house-style frontmatter + body. Trigger phrases must include /<name> and 5-9 natural phrases. allowed-tools = least privilege (only what steps use). Keep all gotchas as explicit rules in body.

5. Write to canonical location

~/.claude/skills/<name>/SKILL.md

This is canonical. NOTE: ~/.claude/commands/<name>.md ALSO registers /<name> — custom commands are merged into skills — but skills/<name>/SKILL.md is the house standard. Use it unless the user explicitly wants a bare command.

6. Validate (run the checklist below)

7. Offer the two add-ons

• /command alias — the skill name already gives /<name>. Only create a separate commands\<name>.md if the user wants a different alias or a thin wrapper. Ask before creating.
• MEMORY.md pointer — offer to append ONE line to your memory manifest (~/.claude/.../memory/MEMORY.md) so the skill is discoverable later. Keep it to the manifest format (one line, per memory-hygiene rule — manifest only, no dump).

Validation checklist (run before declaring done)

• name: in frontmatter == folder name == kebab-case
• description: is a pipe block with a prose blurb
• Trigger when user says: line present with 5-9 literal phrases incl. /<name>
• Auto-trigger heuristic present (or consciously omitted)
• allowed-tools lists ONLY tools the steps use (least privilege)
• Steps are runnable — no hand-wave; order-matters gotchas called out
• All paths are absolute or ~/-relative, OS-appropriate
• PowerShell-safe commands where shell is shown ($null not /dev/null, $env:VAR)
• NO secrets / API keys / tokens hardcoded — reference where they live instead
• Every gotcha the user gave is encoded as an explicit rule
• Output artifact path is explicit and absolute
• Frontmatter is valid YAML (pipe block indented, no tabs)
• Not facts-only (would belong in CLAUDE.md) — it's a real procedure

Output format (what to report after writing)

SKILL CREATED: <name>
Path: ~/.claude/skills/<name>/SKILL.md
Triggers: <list>
Tools: <allowed-tools>
Validation: <N/N checks passed, or list failures>
Add-ons offered: /command alias? <y/n>  MEMORY.md pointer? <y/n>
Reload note: new skills register on next session — /clear or restart to pick it up.

Adopting a loose skill file

A common first use: an unfiled-but-good SKILL.md is sitting somewhere outside the canonical skills tree (e.g. a Desktop or Downloads folder), so no session can auto-invoke it. Filing it is a canonical use of skill-builder.

To adopt it:

1. Read the loose *-SKILL.md. Check its frontmatter name: and whether it's already house-style — often minimal rework is needed.
2. Create folder ~/.claude/skills/<name>/.
3. Write the content to ~/.claude/skills/<name>/SKILL.md (verify name == folder == kebab-case).
4. Run the validation checklist against it. (If it references helper files under prompts/, templates/, references/ that don't exist yet — either create stubs or strip the ## Files section so it doesn't promise missing files.)
5. Offer a one-line MEMORY.md pointer.
6. Remove any stale copies only after confirming the filed version reads back correctly — ask first.

Failure modes + fixes

Failure	Cause	Fix
New skill never auto-invokes	Weak/missing trigger phrases in description	Add 5-9 literal phrases incl. /<name> + auto-trigger heuristic
Skill loaded but ignored	name: ≠ folder name	Make them identical, kebab-case
Context bloat, zero leverage	It was facts, not a procedure	Move to CLAUDE.md; delete the skill
Steps not reproducible	Vague "do the thing" steps	Re-elicit real commands + order-matters gotchas
Secret leaked into skill file	Hardcoded key/token	Replace with pointer to where the secret lives
/command doesn't appear	New skill not loaded this session	/clear or restart — skills register at session start
Path breaks on this box	Unix paths / forward slashes	Windows absolute paths, backslashes, PowerShell-safe
Duplicate skill	Didn't glob for existing name	Glob **\<name>\SKILL.md before writing

Anti-patterns

• ❌ Writing a skill for facts that belong in CLAUDE.md
• ❌ Thin trigger list (1-2 phrases) → skill is invisible to auto-invocation
• ❌ Granting all tools "to be safe" → grant only what steps use
• ❌ Inventing steps the user never confirmed
• ❌ Dropping the user's hard-won gotchas to keep it short — gotchas are the value
• ❌ Writing to a random folder instead of .claude/skills/<name>/
• ❌ Unix paths / /dev/null on a Windows box
• ❌ Re-asking inputs already stated in the conversation
• ❌ Promising ## Files helpers that don't exist

Cost model

• Cheap: one file write + a few globs. Worth it any time a workflow recurs ≥2×.
• The leverage is downstream: a well-triggered skill saves the re-prompt cost on every future run and keeps idle token cost at ~0 (loads only when invoked).
• Skip only for true one-offs you'll never repeat.

---

House references: ~/.claude/skills/fanout-ship/SKILL.md, ~/.claude/skills/upwork-proposal/SKILL.md, and ~/.claude/skills/code-audit-fanout/SKILL.md (once filed) are the canonical style exemplars. When in doubt, copy their density and structure.