[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M74MZK0SMAMC75BWTSKFP8JG":3,"skill-same:01M74MZK0SMAMC75BWTSKFP8JG":80},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":29,"ownerDescription":30,"updatedAt":31,"install":32,"resources":45},"01M74MZK0SMAMC75BWTSKFP8JG","the-keymaker",null,"Use when the user wants to create a new agent skill, capture a repeatable workflow as a skill, edit or improve an existing skill, debug why a skill isn't triggering, validate a SKILL.md, or learn how skills work. Triggers on phrases like \"create a skill\", \"write a SKILL.md\", \"turn this into a skill\", \"my skill isn't loading\", \"validate this skill\", or when the user describes a multi-step workflow they want to package for agents. Applies to any framework that supports the Agent Skills format (OpenCode, Claude Code, Codex, Gemini CLI, etc.).","eliharoun\u002Fagent-smith","eliharoun","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F115818443?v=4","01M74MYZARZ9S260JJE912RQW7","Elias Haroun","01M74MYZBCRJ6QBDWTM07XRS1G",0,"MIT","https:\u002F\u002Fgithub.com\u002Feliharoun\u002Fagent-smith\u002Fblob\u002Fmain\u002Fskills\u002Fthe-keymaker\u002FSKILL.md",[],[],"2026-11-11 15:11:14",false,"---\nname: the-keymaker\ndescription: Use when the user wants to create a new agent skill, capture a repeatable workflow as a skill, edit or improve an existing skill, debug why a skill isn't triggering, validate a SKILL.md, or learn how skills work. Triggers on phrases like \"create a skill\", \"write a SKILL.md\", \"turn this into a skill\", \"my skill isn't loading\", \"validate this skill\", or when the user describes a multi-step workflow they want to package for agents. Applies to any framework that supports the Agent Skills format (OpenCode, Claude Code, Codex, Gemini CLI, etc.).\nlicense: MIT\n---\n\n# The Keymaker\n\nA meta-skill that forges and unlocks new agent capabilities. The Keymaker guides you through creating, improving, validating, and debugging agent skills — the keys that unlock new possibilities for your agents. The output is a `SKILL.md` file (plus optional supporting files) that conforms to the [Agent Skills](https:\u002F\u002Fagentskills.io) open standard and works across OpenCode, Claude Code, Codex, and any other framework that adopts it.\n\n## Core principle\n\n**A skill is a reference guide for a proven technique, pattern, or tool — not a narrative about how you solved a problem once.** Skills are loaded on demand into an agent's context, so they must be:\n\n- **Discoverable** — a description that triggers reliably\n- **Scannable** — clear structure, quick reference tables\n- **Bulletproof** — explanations that resist rationalization\n- **Validated** — passes `scripts\u002Fvalidate-skill.sh` before shipping\n\n**Iron Law: no skill ships without a failing test first.** You cannot know whether your skill teaches the right thing if you have not first watched an agent fail without it. This applies to new skills *and* edits to existing skills.\n\n## When to use this skill\n\nTrigger when the user says any of:\n\n- \"Create a skill for…\" \u002F \"Turn this workflow into a skill\"\n- \"Improve \u002F edit \u002F fix the X skill\"\n- \"My skill isn't triggering\" \u002F \"the agent ignores my skill\"\n- \"Validate this skill\" \u002F \"is this SKILL.md valid?\"\n- \"How do I write a skill?\"\n- \"Package this as a skill\"\n\nAlso trigger proactively when the user describes a multi-step workflow they keep repeating across sessions or projects — that's a skill waiting to happen.\n\n## The workflow\n\n```\nRED      Phase 1 — Capture intent + run baseline (agent without skill)\n         Phase 2 — Choose structural approach\nGREEN    Phase 3 — Draft SKILL.md (+ optional bundled files)\nGATE     Phase 4 — Validate (HARD GATE: validator must pass)\nREFACTOR Phase 5 — Sanity-test with realistic prompts; iterate\nDEPLOY   Phase 6 — Place in correct directory; smoke test\n```\n\nUse TodoWrite (or your agent's todo equivalent) to track each phase. Enter at whichever phase matches the user's current state — not necessarily Phase 1.\n\n---\n\n## Phase 1 — RED: Capture intent and baseline\n\n### 1a. Interview the user\n\nAsk every question below in order. For questions where the conversation already supplied an answer, present that answer as a **suggested default** alongside the question — but require the user's explicit confirmation before moving on. Never silently skip a question because you think you know the answer; silent inference produces skills the user didn't actually agree to. Prefer multiple choice.\n\n1. **Purpose.** What should this skill enable the agent to do? (one or two sentences)\n2. **Triggers.** When should it trigger? List user phrases, file types, error symptoms, situations.\n3. **Type.** Is this a **discipline** skill (a rule\u002Fprocess), a **technique** (how-to), a **pattern** (mental model), or a **reference** (docs\u002FAPI)? This determines testing strategy.\n4. **Bundled resources.** Will this need scripts, references, or assets, or is a single SKILL.md enough?\n5. **Target directory.** Where should it live? Default: `skills\u002F\u003Cname>\u002F` in the current repo. Never under `~\u002F.claude\u002F`, `~\u002F.config\u002Fopencode\u002F`, or `~\u002F.agents\u002F` — those are install paths.\n\nFor workflows the user already demonstrated in conversation, *extract* the candidate steps, tools used, corrections made, and input\u002Foutput formats — then present them back **per question** as suggested defaults the user explicitly confirms or corrects. Do not collapse multiple questions into a single \"here's what I extracted, OK to proceed?\" confirmation block; ask each question, surface the extracted answer as the suggested default, and wait for an answer.\n\n### 1b. Run the baseline\n\n**Before writing a single line of the skill**, prove the failure mode exists. Pick 2–3 realistic prompts a user would actually type. Run an agent on them *without* the skill and document verbatim:\n\n- What did the agent do?\n- What rationalizations did it use? (\"This is just a simple…\", \"I'll skip this because…\")\n- Which prompts triggered the worst behavior?\n\nIf the agent already does the right thing without your skill, **stop**. You don't need a skill — the model already handles it.\n\nSave baseline notes; you will use them in Phase 3 to target your skill at *specific* observed failures, not hypothetical ones.\n\n---\n\n## Phase 2 — Choose a structural approach\n\nPick the structure based on Phase 1 answers. Recommend one, confirm with the user.\n\n| Structure | Best for | Layout |\n|---|---|---|\n| **Single-file** | Skills under ~300 lines of total content | Just `SKILL.md` |\n| **SKILL.md + references\u002F** | Total content > ~300 lines, or distinct sub-domains | `SKILL.md` (workflow) + `references\u002F\u003Ctopic>.md` (detail) |\n| **Workflow-based** | Multi-step procedures | `SKILL.md` is a phase sequence; one reference per phase |\n| **Task-based** | Tool collections \u002F menu of operations | `SKILL.md` is a task index; one reference per task |\n| **Reference-based** | Navigation skills, large knowledge bases | `SKILL.md` is a thin router; references hold the knowledge |\n\nWhichever structure you pick, keep `SKILL.md` under **500 lines** (validator hard limit) and aim for **\u003C 400 lines** (validator warning).\n\n---\n\n## Phase 3 — GREEN: Draft\n\n### 3a. Scaffold\n\nUse the bundled scaffolder to create the directory structure:\n\n```bash\n.\u002Fscripts\u002Fscaffold-skill.sh \u003Cskill-name>\n```\n\nThis creates `\u003Ctarget>\u002F\u003Cskill-name>\u002F` with `SKILL.md` (from template), `scripts\u002F`, and `references\u002F`. It refuses to write into install paths (`~\u002F.claude\u002F`, `~\u002F.config\u002Fopencode\u002F`, `~\u002F.agents\u002F`).\n\n### 3b. Write the frontmatter\n\n```yaml\n---\nname: skill-name-with-hyphens\ndescription: Use when [specific triggering conditions, symptoms, contexts]\nlicense: MIT\n---\n```\n\n**Required:** `name`, `description`. Everything else is optional.\n\n**`name` rules** (validator-enforced):\n- 1–64 characters\n- Lowercase alphanumeric with single hyphens (`^[a-z0-9]+(-[a-z0-9]+)*$`)\n- Must match the directory name exactly\n\n**`description` rules:**\n- 1–1024 characters total\n- Written in **third person**, starts with \"Use when…\"\n- Describes **WHEN to use**, not **HOW the skill works internally** — descriptions that summarize workflow create a shortcut the agent takes instead of reading the body\n\n**When drafting or revising the description**, read [references\u002Fwriting-effective-descriptions.md](references\u002Fwriting-effective-descriptions.md). The four principles + before\u002Fafter rewrites in that file are the difference between a skill that triggers and one that sits dormant.\n\n**For client-specific frontmatter fields** (`disable-model-invocation`, `allowed-tools`, `paths`, etc.), read [references\u002Ffrontmatter-reference.md](references\u002Ffrontmatter-reference.md). It's a 14-field × 4-client matrix — load it when you need anything beyond `name` + `description`.\n\n### 3c. Write the body\n\nUse this skeleton as a starting point; adapt to skill type:\n\n```markdown\n# Skill Name\n\n## Overview\nWhat this is, in 1–2 sentences. State the core principle.\n\n## When to use this skill\nBulleted symptoms \u002F triggers (mirrors and expands the description).\n\"Do NOT use when…\" clauses for adjacent-but-different cases.\n\n## Core concepts (optional)\n2–5 domain ideas the agent needs before executing. Skip if self-explanatory.\n\n## Workflow \u002F The pattern\nThe actual technique. Inline code for short examples; link to a file for long ones.\n\n## Quick reference\nTable or short bullets for the most common operations. Optimize for scanning.\n\n## Common mistakes\nWhat goes wrong + how to fix it. Pulled directly from baseline observations.\n\n## Gotchas (optional)\nNon-obvious facts that defy reasonable assumptions. Often the highest-value section.\n\n## Red flags (for discipline skills)\nThoughts that mean STOP — the agent is rationalizing.\n```\n\n### 3d. Writing principles\n\n- **Imperative voice.** \"Run the baseline.\" Not \"You should consider running…\"\n- **Explain WHY, not just WHAT.** Modern LLMs have good theory of mind. A two-sentence rationale beats five `MUST`s.\n- **One excellent example beats five mediocre ones.** Don't port to multiple languages. Pick the most relevant language; agents port well on demand.\n- **Procedures over declarations.** General approaches the agent can apply, not specific one-off answers.\n- **Keywords for discoverability.** Sprinkle the words an agent would search for: error messages, library names, symptoms, synonyms.\n- **No narrative storytelling.** \"In session 2025-04-30 we discovered…\" is wrong. Skills are reference material, not war stories.\n- **Cross-reference, don't duplicate.** Link to other skills by name. Never `@`-link or force-load other skills' content — it burns context.\n- **Address baseline failures specifically.** For each rationalization observed in Phase 1b, add an explicit counter — not generic discipline.\n\n### 3e. Bundled scripts\n\nAdd scripts to `scripts\u002F` only when they pull their weight: deterministic logic the agent would otherwise rewrite each run, validation, safety checks, or token-heavy utilities. **Before writing a script**, read [references\u002Fscript-guidelines.md](references\u002Fscript-guidelines.md) for portability rules (no `jq`, cross-platform `sed`, executable bit, etc.) and templates.\n\nEvery bundled script **must** be documented in SKILL.md with: what it does, when to use it, parameters, example invocation, and expected output. The validator does not enforce this, but undocumented scripts get ignored by the agent.\n\n---\n\n## Phase 4 — GATE: Validate\n\nThis is a **hard gate**. Run the validator against the new skill:\n\n```bash\n.\u002Fscripts\u002Fvalidate-skill.sh \u003Cpath-to-skill-dir-or-SKILL.md>\n```\n\nThe validator runs 15 checks across structure, frontmatter, body, supporting files, and safety. Any ❌ blocks progression. Common failures and fixes:\n\n| Error | Fix |\n|---|---|\n| `name does not match directory` | Rename either the directory or the frontmatter field so they agree |\n| `description is N chars; must be 1-1024` | Tighten the description; move details to body |\n| `body is N lines; must be ≤ 500` | Extract content into `references\u002F\u003Ctopic>.md` |\n| `referenced script not executable` | `chmod +x scripts\u002F\u003Cname>.sh` |\n| `referenced file missing` | Create the file or remove the reference |\n| `broken markdown link` | Fix the path or remove the link |\n| `possible secret detected in body` | Remove the secret; use a placeholder or env var |\n| `first body line must be an H1 heading` | Add `# Skill Name` after the closing `---` |\n\nFix every ❌ and re-run until exit code is 0. Warnings (⚠️) are advisory but worth addressing.\n\n### scripts\u002Fvalidate-skill.sh\n\nValidates a SKILL.md against the Agent Skills spec.\n\n**When to use:** Phase 4 (gate), after every revision in Phase 5, and before commit.\n\n**Usage:** `.\u002Fscripts\u002Fvalidate-skill.sh \u003Cpath-to-SKILL.md-or-skill-dir>`\n\n**Output:** line-per-check with ✅\u002F⚠️\u002F❌ icons, summary line at the end. Exit 0 on pass (warnings allowed), 1 on error, 2 on usage failure.\n\n### scripts\u002Fscaffold-skill.sh\n\nCreates a new skill directory from the template.\n\n**When to use:** Phase 3a, to create a new skill skeleton.\n\n**Usage:** `.\u002Fscripts\u002Fscaffold-skill.sh [-y] \u003Cskill-name> [target-parent-dir]`\n\n**Output:** creates `\u003Ctarget>\u002F\u003Cskill-name>\u002F` with `SKILL.md`, `scripts\u002F`, `references\u002F`. Refuses to write under agent install paths.\n\n---\n\n## Phase 5 — REFACTOR: Sanity-test and iterate\n\n### 5a. Generate test prompts\n\nSave 2–3 realistic test prompts to `\u003Cskill>\u002Fevals.json` using `assets\u002Fevals.json.template`. Each prompt should be something a real user would plausibly type, varying in phrasing and explicitness.\n\n### 5b. Run them\n\n**With subagent support:** dispatch one subagent per prompt using the host's subagent mechanism (OpenCode `task` tool, Claude Code subagent system, etc.). The subagent must load the new skill and produce output you can inspect.\n\n**Without subagent support:** run each prompt in the current session and warn the user that isolation is weaker (you have the drafting context in your head). Proceed with qualitative review.\n\nFor discipline skills, combine pressures (time + sunk cost + authority + exhaustion) — that's where loopholes hide.\n\n### 5c. Iterate based on feedback\n\nFour guiding principles:\n\n1. **Generalize from feedback.** The skill will be used far more than 3 times. Don't overfit to the test prompts — find the general pattern behind each piece of feedback.\n2. **Keep the body lean.** Remove instructions that aren't pulling their weight. Unnecessary prose competes for the agent's attention.\n3. **Explain the *why*.** Reframe heavy-handed `MUST` directives into reasoned guidance. LLMs follow well-explained *why*s more reliably than blunt mandates.\n4. **Extract reusable scripts.** If multiple test runs caused the agent to write the same helper, bundle it in `scripts\u002F` once.\n\nFor each new rationalization the agent finds, add an explicit counter to a \"Common rationalizations\" table. **Re-run Phase 4 (validate) after every revision.** Loop Phases 5a–5c until either the user is satisfied, feedback is empty, or three iterations go by without meaningful improvement.\n\n---\n\n## Phase 6 — DEPLOY: Place and smoke-test\n\n### 6a. Place the skill\n\n| Platform | Project (per-repo) | Global (per-user) |\n|---|---|---|\n| OpenCode | `.opencode\u002Fskills\u002F\u003Cname>\u002FSKILL.md` | `~\u002F.config\u002Fopencode\u002Fskills\u002F\u003Cname>\u002FSKILL.md` |\n| Claude Code | `.claude\u002Fskills\u002F\u003Cname>\u002FSKILL.md` | `~\u002F.claude\u002Fskills\u002F\u003Cname>\u002FSKILL.md` |\n| Codex | `.agents\u002Fskills\u002F\u003Cname>\u002FSKILL.md` | `~\u002F.agents\u002Fskills\u002F\u003Cname>\u002FSKILL.md` |\n\n**Cross-platform tip:** OpenCode reads from all three project paths and the matching global paths. Placing your skill under `.claude\u002Fskills\u002F` makes it usable by both Claude Code and OpenCode without duplication.\n\n**Always edit in your source repo** and symlink (or copy) into install paths. Never edit `SKILL.md` files inside `~\u002F.claude\u002F` or `~\u002F.config\u002Fopencode\u002F` directly — they're consumption locations and may be overwritten by package managers.\n\n### 6b. Smoke-test\n\nOpen a fresh agent session. Verify:\n\n1. The skill appears in the agent's available skills list\n2. A natural-language prompt matching the description loads the skill\n3. The agent follows the skill's instructions\n\n**If the skill doesn't appear:** check `SKILL.md` is uppercase, run the validator, ensure the directory name matches `name`.\n\n**If it appears but doesn't trigger:** the description is wrong. Add the user's actual phrasing as a trigger keyword. Repeat until it triggers reliably. See `references\u002Fwriting-effective-descriptions.md` for rewriting strategies.\n\n---\n\n## Quick reference\n\n| Task | Action |\n|---|---|\n| Create a new skill | Run all six phases. Don't skip the baseline. |\n| Edit existing skill | Re-run baseline scenarios first to confirm the new behavior is needed. Re-validate after. |\n| Skill not triggering | Description problem. Read `references\u002Fwriting-effective-descriptions.md`. Add user's actual words. |\n| Skill triggers too often | Description too broad. Add \"Do NOT use when…\" or split into two skills. |\n| Long reference material | Move to `references\u002F\u003Ctopic>.md`, link from SKILL.md with a one-line \"load when…\" hint. |\n| Reusable code logic | Put in `scripts\u002F`, document in SKILL.md with usage block. |\n| Need cross-client field info | `references\u002Ffrontmatter-reference.md` |\n| Need script portability rules | `references\u002Fscript-guidelines.md` |\n| Validate before committing | `.\u002Fscripts\u002Fvalidate-skill.sh \u003Cpath>` |\n| Scaffold a fresh skill | `.\u002Fscripts\u002Fscaffold-skill.sh \u003Cname>` |\n\n## Common mistakes\n\n| Mistake | Fix |\n|---|---|\n| Description summarizes workflow | Rewrite as triggers only (\"Use when X, Y, Z\"). The body teaches the workflow. |\n| Skill name has uppercase \u002F underscores | Use lowercase + single hyphens only. The validator enforces this. |\n| Directory name ≠ `name` field | Make them identical. The validator enforces this. |\n| Frontmatter > 1024 chars | Trim description; move details to body. |\n| Multi-language code examples | Pick one language; the agent ports on demand. |\n| `MUST` \u002F `NEVER` everywhere with no rationale | Replace with one-sentence explanations of *why*. |\n| Skill written without baseline | Delete it. Run baseline. Start over. |\n| Edited a skill without re-validating | An edit is a new skill. Re-run validator. |\n| Forgot to document a bundled script | Add a script-doc block to SKILL.md. Without it, the agent ignores the script. |\n| Editing `~\u002F.claude\u002Fskills\u002F\u003Cname>\u002F` directly | Edit in source repo. Symlink into install path. |\n| Body grew past 400 lines | Extract sections into `references\u002F`. The validator warns at 400, errors at 500. |\n\n## Red flags — STOP and start over\n\nIf you catch yourself thinking any of these, you are about to ship a bad skill:\n\n- \"I don't need to baseline, the failure is obvious\"\n- \"This is just a small edit, no need to re-validate\"\n- \"The description is fine, the agent will figure it out\"\n- \"I'll add more examples instead of fixing the structure\"\n- \"It works for me, ship it\"\n- \"I know what the agent does without running it\"\n- \"The validator's wrong about this one, I'll skip it\"\n\n**All of these mean: run the baseline. Validate. Test. Then ship.**\n\n## When NOT to create a skill\n\n- The behavior is project-specific → put it in `CLAUDE.md` \u002F `AGENTS.md` \u002F `opencode.md` instead\n- It's a one-off solution → just do it inline\n- It's a mechanical constraint enforceable by a linter or hook → automate it deterministically\n- The agent already does the right thing without it (verified by baseline)\n- It duplicates an existing skill → improve the existing one\n\n## The bottom line\n\n**Creating skills is TDD applied to documentation.** Same iron law (no skill without a failing test first), same cycle (RED → GREEN → REFACTOR → DEPLOY), same gate (the validator must pass).\n\nIf you follow TDD for code, follow it for skills. Same discipline, different artifact — and a real validator standing between drafts and shipping.\n","# The Keymaker\n\nA meta-skill that forges and unlocks new agent capabilities. The Keymaker guides you through creating, improving, validating, and debugging agent skills — the keys that unlock new possibilities for your agents. The output is a `SKILL.md` file (plus optional supporting files) that conforms to the [Agent Skills](https:\u002F\u002Fagentskills.io) open standard and works across OpenCode, Claude Code, Codex, and any other framework that adopts it.\n\n## Core principle\n\n**A skill is a reference guide for a proven technique, pattern, or tool — not a narrative about how you solved a problem once.** Skills are loaded on demand into an agent's context, so they must be:\n\n- **Discoverable** — a description that triggers reliably\n- **Scannable** — clear structure, quick reference tables\n- **Bulletproof** — explanations that resist rationalization\n- **Validated** — passes `scripts\u002Fvalidate-skill.sh` before shipping\n\n**Iron Law: no skill ships without a failing test first.** You cannot know whether your skill teaches the right thing if you have not first watched an agent fail without it. This applies to new skills *and* edits to existing skills.\n\n## When to use this skill\n\nTrigger when the user says any of:\n\n- \"Create a skill for…\" \u002F \"Turn this workflow into a skill\"\n- \"Improve \u002F edit \u002F fix the X skill\"\n- \"My skill isn't triggering\" \u002F \"the agent ignores my skill\"\n- \"Validate this skill\" \u002F \"is this SKILL.md valid?\"\n- \"How do I write a skill?\"\n- \"Package this as a skill\"\n\nAlso trigger proactively when the user describes a multi-step workflow they keep repeating across sessions or projects — that's a skill waiting to happen.\n\n## The workflow\n\n```\nRED      Phase 1 — Capture intent + run baseline (agent without skill)\n         Phase 2 — Choose structural approach\nGREEN    Phase 3 — Draft SKILL.md (+ optional bundled files)\nGATE     Phase 4 — Validate (HARD GATE: validator must pass)\nREFACTOR Phase 5 — Sanity-test with realistic prompts; iterate\nDEPLOY   Phase 6 — Place in correct directory; smoke test\n```\n\nUse TodoWrite (or your agent's todo equivalent) to track each phase. Enter at whichever phase matches the user's current state — not necessarily Phase 1.\n\n---\n\n## Phase 1 — RED: Capture intent and baseline\n\n### 1a. Interview the user\n\nAsk every question below in order. For questions where the conversation already supplied an answer, present that answer as a **suggested default** alongside the question — but require the user's explicit confirmation before moving on. Never silently skip a question because you think you know the answer; silent inference produces skills the user didn't actually agree to. Prefer multiple choice.\n\n1. **Purpose.** What should this skill enable the agent to do? (one or two sentences)\n2. **Triggers.** When should it trigger? List user phrases, file types, error symptoms, situations.\n3. **Type.** Is this a **discipline** skill (a rule\u002Fprocess), a **technique** (how-to), a **pattern** (mental model), or a **reference** (docs\u002FAPI)? This determines testing strategy.\n4. **Bundled resources.** Will this need scripts, references, or assets, or is a single SKILL.md enough?\n5. **Target directory.** Where should it live? Default: `skills\u002F\u003Cname>\u002F` in the current repo. Never under `~\u002F.claude\u002F`, `~\u002F.config\u002Fopencode\u002F`, or `~\u002F.agents\u002F` — those are install paths.\n\nFor workflows the user already demonstrated in conversation, *extract* the candidate steps, tools used, corrections made, and input\u002Foutput formats — then present them back **per question** as suggested defaults the user explicitly confirms or corrects. Do not collapse multiple questions into a single \"here's what I extracted, OK to proceed?\" confirmation block; ask each question, surface the extracted answer as the suggested default, and wait for an answer.\n\n### 1b. Run the baseline\n\n**Before writing a single line of the skill**, prove the failure mode exists. Pick 2–3 realistic prompts a user would actually type. Run an agent on them *without* the skill and document verbatim:\n\n- What did the agent do?\n- What rationalizations did it use? (\"This is just a simple…\", \"I'll skip this because…\")\n- Which prompts triggered the worst behavior?\n\nIf the agent already does the right thing without your skill, **stop**. You don't need a skill — the model already handles it.\n\nSave baseline notes; you will use them in Phase 3 to target your skill at *specific* observed failures, not hypothetical ones.\n\n---\n\n## Phase 2 — Choose a structural approach\n\nPick the structure based on Phase 1 answers. Recommend one, confirm with the user.\n\n| Structure | Best for | Layout |\n|---|---|---|\n| **Single-file** | Skills under ~300 lines of total content | Just `SKILL.md` |\n| **SKILL.md + references\u002F** | Total content > ~300 lines, or distinct sub-domains | `SKILL.md` (workflow) + `references\u002F\u003Ctopic>.md` (detail) |\n| **Workflow-based** | Multi-step procedures | `SKILL.md` is a phase sequence; one reference per phase |\n| **Task-based** | Tool collections \u002F menu of operations | `SKILL.md` is a task index; one reference per task |\n| **Reference-based** | Navigation skills, large knowledge bases | `SKILL.md` is a thin router; references hold the knowledge |\n\nWhichever structure you pick, keep `SKILL.md` under **500 lines** (validator hard limit) and aim for **\u003C 400 lines** (validator warning).\n\n---\n\n## Phase 3 — GREEN: Draft\n\n### 3a. Scaffold\n\nUse the bundled scaffolder to create the directory structure:\n\n```bash\n.\u002Fscripts\u002Fscaffold-skill.sh \u003Cskill-name>\n```\n\nThis creates `\u003Ctarget>\u002F\u003Cskill-name>\u002F` with `SKILL.md` (from template), `scripts\u002F`, and `references\u002F`. It refuses to write into install paths (`~\u002F.claude\u002F`, `~\u002F.config\u002Fopencode\u002F`, `~\u002F.agents\u002F`).\n\n### 3b. Write the frontmatter\n\n```yaml\n---\nname: skill-name-with-hyphens\ndescription: Use when [specific triggering conditions, symptoms, contexts]\nlicense: MIT\n---\n```\n\n**Required:** `name`, `description`. Everything else is optional.\n\n**`name` rules** (validator-enforced):\n- 1–64 characters\n- Lowercase alphanumeric with single hyphens (`^[a-z0-9]+(-[a-z0-9]+)*$`)\n- Must match the directory name exactly\n\n**`description` rules:**\n- 1–1024 characters total\n- Written in **third person**, starts with \"Use when…\"\n- Describes **WHEN to use**, not **HOW the skill works internally** — descriptions that summarize workflow create a shortcut the agent takes instead of reading the body\n\n**When drafting or revising the description**, read [references\u002Fwriting-effective-descriptions.md](references\u002Fwriting-effective-descriptions.md). The four principles + before\u002Fafter rewrites in that file are the difference between a skill that triggers and one that sits dormant.\n\n**For client-specific frontmatter fields** (`disable-model-invocation`, `allowed-tools`, `paths`, etc.), read [references\u002Ffrontmatter-reference.md](references\u002Ffrontmatter-reference.md). It's a 14-field × 4-client matrix — load it when you need anything beyond `name` + `description`.\n\n### 3c. Write the body\n\nUse this skeleton as a starting point; adapt to skill type:\n\n```markdown\n# Skill Name\n\n## Overview\nWhat this is, in 1–2 sentences. State the core principle.\n\n## When to use this skill\nBulleted symptoms \u002F triggers (mirrors and expands the description).\n\"Do NOT use when…\" clauses for adjacent-but-different cases.\n\n## Core concepts (optional)\n2–5 domain ideas the agent needs before executing. Skip if self-explanatory.\n\n## Workflow \u002F The pattern\nThe actual technique. Inline code for short examples; link to a file for long ones.\n\n## Quick reference\nTable or short bullets for the most common operations. Optimize for scanning.\n\n## Common mistakes\nWhat goes wrong + how to fix it. Pulled directly from baseline observations.\n\n## Gotchas (optional)\nNon-obvious facts that defy reasonable assumptions. Often the highest-value section.\n\n## Red flags (for discipline skills)\nThoughts that mean STOP — the agent is rationalizing.\n```\n\n### 3d. Writing principles\n\n- **Imperative voice.** \"Run the baseline.\" Not \"You should consider running…\"\n- **Explain WHY, not just WHAT.** Modern LLMs have good theory of mind. A two-sentence rationale beats five `MUST`s.\n- **One excellent example beats five mediocre ones.** Don't port to multiple languages. Pick the most relevant language; agents port well on demand.\n- **Procedures over declarations.** General approaches the agent can apply, not specific one-off answers.\n- **Keywords for discoverability.** Sprinkle the words an agent would search for: error messages, library names, symptoms, synonyms.\n- **No narrative storytelling.** \"In session 2025-04-30 we discovered…\" is wrong. Skills are reference material, not war stories.\n- **Cross-reference, don't duplicate.** Link to other skills by name. Never `@`-link or force-load other skills' content — it burns context.\n- **Address baseline failures specifically.** For each rationalization observed in Phase 1b, add an explicit counter — not generic discipline.\n\n### 3e. Bundled scripts\n\nAdd scripts to `scripts\u002F` only when they pull their weight: deterministic logic the agent would otherwise rewrite each run, validation, safety checks, or token-heavy utilities. **Before writing a script**, read [references\u002Fscript-guidelines.md](references\u002Fscript-guidelines.md) for portability rules (no `jq`, cross-platform `sed`, executable bit, etc.) and templates.\n\nEvery bundled script **must** be documented in SKILL.md with: what it does, when to use it, parameters, example invocation, and expected output. The validator does not enforce this, but undocumented scripts get ignored by the agent.\n\n---\n\n## Phase 4 — GATE: Validate\n\nThis is a **hard gate**. Run the validator against the new skill:\n\n```bash\n.\u002Fscripts\u002Fvalidate-skill.sh \u003Cpath-to-skill-dir-or-SKILL.md>\n```\n\nThe validator runs 15 checks across structure, frontmatter, body, supporting files, and safety. Any ❌ blocks progression. Common failures and fixes:\n\n| Error | Fix |\n|---|---|\n| `name does not match directory` | Rename either the directory or the frontmatter field so they agree |\n| `description is N chars; must be 1-1024` | Tighten the description; move details to body |\n| `body is N lines; must be ≤ 500` | Extract content into `references\u002F\u003Ctopic>.md` |\n| `referenced script not executable` | `chmod +x scripts\u002F\u003Cname>.sh` |\n| `referenced file missing` | Create the file or remove the reference |\n| `broken markdown link` | Fix the path or remove the link |\n| `possible secret detected in body` | Remove the secret; use a placeholder or env var |\n| `first body line must be an H1 heading` | Add `# Skill Name` after the closing `---` |\n\nFix every ❌ and re-run until exit code is 0. Warnings (⚠️) are advisory but worth addressing.\n\n### scripts\u002Fvalidate-skill.sh\n\nValidates a SKILL.md against the Agent Skills spec.\n\n**When to use:** Phase 4 (gate), after every revision in Phase 5, and before commit.\n\n**Usage:** `.\u002Fscripts\u002Fvalidate-skill.sh \u003Cpath-to-SKILL.md-or-skill-dir>`\n\n**Output:** line-per-check with ✅\u002F⚠️\u002F❌ icons, summary line at the end. Exit 0 on pass (warnings allowed), 1 on error, 2 on usage failure.\n\n### scripts\u002Fscaffold-skill.sh\n\nCreates a new skill directory from the template.\n\n**When to use:** Phase 3a, to create a new skill skeleton.\n\n**Usage:** `.\u002Fscripts\u002Fscaffold-skill.sh [-y] \u003Cskill-name> [target-parent-dir]`\n\n**Output:** creates `\u003Ctarget>\u002F\u003Cskill-name>\u002F` with `SKILL.md`, `scripts\u002F`, `references\u002F`. Refuses to write under agent install paths.\n\n---\n\n## Phase 5 — REFACTOR: Sanity-test and iterate\n\n### 5a. Generate test prompts\n\nSave 2–3 realistic test prompts to `\u003Cskill>\u002Fevals.json` using `assets\u002Fevals.json.template`. Each prompt should be something a real user would plausibly type, varying in phrasing and explicitness.\n\n### 5b. Run them\n\n**With subagent support:** dispatch one subagent per prompt using the host's subagent mechanism (OpenCode `task` tool, Claude Code subagent system, etc.). The subagent must load the new skill and produce output you can inspect.\n\n**Without subagent support:** run each prompt in the current session and warn the user that isolation is weaker (you have the drafting context in your head). Proceed with qualitative review.\n\nFor discipline skills, combine pressures (time + sunk cost + authority + exhaustion) — that's where loopholes hide.\n\n### 5c. Iterate based on feedback\n\nFour guiding principles:\n\n1. **Generalize from feedback.** The skill will be used far more than 3 times. Don't overfit to the test prompts — find the general pattern behind each piece of feedback.\n2. **Keep the body lean.** Remove instructions that aren't pulling their weight. Unnecessary prose competes for the agent's attention.\n3. **Explain the *why*.** Reframe heavy-handed `MUST` directives into reasoned guidance. LLMs follow well-explained *why*s more reliably than blunt mandates.\n4. **Extract reusable scripts.** If multiple test runs caused the agent to write the same helper, bundle it in `scripts\u002F` once.\n\nFor each new rationalization the agent finds, add an explicit counter to a \"Common rationalizations\" table. **Re-run Phase 4 (validate) after every revision.** Loop Phases 5a–5c until either the user is satisfied, feedback is empty, or three iterations go by without meaningful improvement.\n\n---\n\n## Phase 6 — DEPLOY: Place and smoke-test\n\n### 6a. Place the skill\n\n| Platform | Project (per-repo) | Global (per-user) |\n|---|---|---|\n| OpenCode | `.opencode\u002Fskills\u002F\u003Cname>\u002FSKILL.md` | `~\u002F.config\u002Fopencode\u002Fskills\u002F\u003Cname>\u002FSKILL.md` |\n| Claude Code | `.claude\u002Fskills\u002F\u003Cname>\u002FSKILL.md` | `~\u002F.claude\u002Fskills\u002F\u003Cname>\u002FSKILL.md` |\n| Codex | `.agents\u002Fskills\u002F\u003Cname>\u002FSKILL.md` | `~\u002F.agents\u002Fskills\u002F\u003Cname>\u002FSKILL.md` |\n\n**Cross-platform tip:** OpenCode reads from all three project paths and the matching global paths. Placing your skill under `.claude\u002Fskills\u002F` makes it usable by both Claude Code and OpenCode without duplication.\n\n**Always edit in your source repo** and symlink (or copy) into install paths. Never edit `SKILL.md` files inside `~\u002F.claude\u002F` or `~\u002F.config\u002Fopencode\u002F` directly — they're consumption locations and may be overwritten by package managers.\n\n### 6b. Smoke-test\n\nOpen a fresh agent session. Verify:\n\n1. The skill appears in the agent's available skills list\n2. A natural-language prompt matching the description loads the skill\n3. The agent follows the skill's instructions\n\n**If the skill doesn't appear:** check `SKILL.md` is uppercase, run the validator, ensure the directory name matches `name`.\n\n**If it appears but doesn't trigger:** the description is wrong. Add the user's actual phrasing as a trigger keyword. Repeat until it triggers reliably. See `references\u002Fwriting-effective-descriptions.md` for rewriting strategies.\n\n---\n\n## Quick reference\n\n| Task | Action |\n|---|---|\n| Create a new skill | Run all six phases. Don't skip the baseline. |\n| Edit existing skill | Re-run baseline scenarios first to confirm the new behavior is needed. Re-validate after. |\n| Skill not triggering | Description problem. Read `references\u002Fwriting-effective-descriptions.md`. Add user's actual words. |\n| Skill triggers too often | Description too broad. Add \"Do NOT use when…\" or split into two skills. |\n| Long reference material | Move to `references\u002F\u003Ctopic>.md`, link from SKILL.md with a one-line \"load when…\" hint. |\n| Reusable code logic | Put in `scripts\u002F`, document in SKILL.md with usage block. |\n| Need cross-client field info | `references\u002Ffrontmatter-reference.md` |\n| Need script portability rules | `references\u002Fscript-guidelines.md` |\n| Validate before committing | `.\u002Fscripts\u002Fvalidate-skill.sh \u003Cpath>` |\n| Scaffold a fresh skill | `.\u002Fscripts\u002Fscaffold-skill.sh \u003Cname>` |\n\n## Common mistakes\n\n| Mistake | Fix |\n|---|---|\n| Description summarizes workflow | Rewrite as triggers only (\"Use when X, Y, Z\"). The body teaches the workflow. |\n| Skill name has uppercase \u002F underscores | Use lowercase + single hyphens only. The validator enforces this. |\n| Directory name ≠ `name` field | Make them identical. The validator enforces this. |\n| Frontmatter > 1024 chars | Trim description; move details to body. |\n| Multi-language code examples | Pick one language; the agent ports on demand. |\n| `MUST` \u002F `NEVER` everywhere with no rationale | Replace with one-sentence explanations of *why*. |\n| Skill written without baseline | Delete it. Run baseline. Start over. |\n| Edited a skill without re-validating | An edit is a new skill. Re-run validator. |\n| Forgot to document a bundled script | Add a script-doc block to SKILL.md. Without it, the agent ignores the script. |\n| Editing `~\u002F.claude\u002Fskills\u002F\u003Cname>\u002F` directly | Edit in source repo. Symlink into install path. |\n| Body grew past 400 lines | Extract sections into `references\u002F`. The validator warns at 400, errors at 500. |\n\n## Red flags — STOP and start over\n\nIf you catch yourself thinking any of these, you are about to ship a bad skill:\n\n- \"I don't need to baseline, the failure is obvious\"\n- \"This is just a small edit, no need to re-validate\"\n- \"The description is fine, the agent will figure it out\"\n- \"I'll add more examples instead of fixing the structure\"\n- \"It works for me, ship it\"\n- \"I know what the agent does without running it\"\n- \"The validator's wrong about this one, I'll skip it\"\n\n**All of these mean: run the baseline. Validate. Test. Then ship.**\n\n## When NOT to create a skill\n\n- The behavior is project-specific → put it in `CLAUDE.md` \u002F `AGENTS.md` \u002F `opencode.md` instead\n- It's a one-off solution → just do it inline\n- It's a mechanical constraint enforceable by a linter or hook → automate it deterministically\n- The agent already does the right thing without it (verified by baseline)\n- It duplicates an existing skill → improve the existing one\n\n## The bottom line\n\n**Creating skills is TDD applied to documentation.** Same iron law (no skill without a failing test first), same cycle (RED → GREEN → REFACTOR → DEPLOY), same gate (the validator must pass).\n\nIf you follow TDD for code, follow it for skills. Same discipline, different artifact — and a real validator standing between drafts and shipping.\n",{"name":5,"license":15,"description":7},"main","4ef532dcbbbaffd2e754afadd2d4f96e0d1f58f7","skills\u002Fthe-keymaker","https:\u002F\u002Fgithub.com\u002Feliharoun\u002Fagent-smith","https:\u002F\u002Fgithub.com\u002Feliharoun","https:\u002F\u002Feliasharoun.com","Software Engineer @ Amazon Fashion & Fitness - Search Ranking | ML\u002FMLOps Engineer | Cloud Engineer | Technical Mentor\r\n","2026-06-16 13:43:24",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add eliharoun\u002Fagent-smith --skill the-keymaker",{"tool":38,"command":39},"bunx","bunx skills add eliharoun\u002Fagent-smith --skill the-keymaker",{"tool":41,"command":42},"pnpm","pnpm dlx skills add eliharoun\u002Fagent-smith --skill the-keymaker","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Feliharoun\u002Fagent-smith\u002Fblob\u002Fmain\u002Fskills\u002Fthe-keymaker\u002FSKILL.md",true,[46,52,56,62,66,70,76],{"path":47,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":50,"sourceHtmlUrl":51},"assets\u002Fevals.json.template","ASSET","资产文件",503,"https:\u002F\u002Fgithub.com\u002Feliharoun\u002Fagent-smith\u002Fblob\u002Fmain\u002Fskills\u002Fthe-keymaker\u002Fassets\u002Fevals.json.template",{"path":53,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":54,"sourceHtmlUrl":55},"assets\u002FSKILL.md.template",1342,"https:\u002F\u002Fgithub.com\u002Feliharoun\u002Fagent-smith\u002Fblob\u002Fmain\u002Fskills\u002Fthe-keymaker\u002Fassets\u002FSKILL.md.template",{"path":57,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":60,"sourceHtmlUrl":61},"references\u002Ffrontmatter-reference.md","REFERENCE","参考文档",6722,"https:\u002F\u002Fgithub.com\u002Feliharoun\u002Fagent-smith\u002Fblob\u002Fmain\u002Fskills\u002Fthe-keymaker\u002Freferences\u002Ffrontmatter-reference.md",{"path":63,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":64,"sourceHtmlUrl":65},"references\u002Fscript-guidelines.md",5018,"https:\u002F\u002Fgithub.com\u002Feliharoun\u002Fagent-smith\u002Fblob\u002Fmain\u002Fskills\u002Fthe-keymaker\u002Freferences\u002Fscript-guidelines.md",{"path":67,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":68,"sourceHtmlUrl":69},"references\u002Fwriting-effective-descriptions.md",7398,"https:\u002F\u002Fgithub.com\u002Feliharoun\u002Fagent-smith\u002Fblob\u002Fmain\u002Fskills\u002Fthe-keymaker\u002Freferences\u002Fwriting-effective-descriptions.md",{"path":71,"resourceType":72,"resourceTypeDesc":73,"sizeBytes":74,"sourceHtmlUrl":75},"scripts\u002Fscaffold-skill.sh","SCRIPT","脚本",3553,"https:\u002F\u002Fgithub.com\u002Feliharoun\u002Fagent-smith\u002Fblob\u002Fmain\u002Fskills\u002Fthe-keymaker\u002Fscripts\u002Fscaffold-skill.sh",{"path":77,"resourceType":72,"resourceTypeDesc":73,"sizeBytes":78,"sourceHtmlUrl":79},"scripts\u002Fvalidate-skill.sh",8274,"https:\u002F\u002Fgithub.com\u002Feliharoun\u002Fagent-smith\u002Fblob\u002Fmain\u002Fskills\u002Fthe-keymaker\u002Fscripts\u002Fvalidate-skill.sh",[81,88],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":19},"01M74MZQNT7Q2Z4J5FDBB18YXP","fixture-skill","Test fixture for skill embedding during export.","https:\u002F\u002Fgithub.com\u002Feliharoun\u002Fagent-smith\u002Fblob\u002Fmain\u002Ftests\u002F_fixtures\u002Fexport-skill\u002Ffixture-skill\u002FSKILL.md",[],[],{"skillNo":89,"name":90,"nameZh":6,"description":91,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":19},"01M74MZC6HWC9NRHGG613KT5PN","the-architect","Use when the user wants to create, modify, or clone an agent for OpenCode, Claude Code, or Codex, or describes a recurring AI helper they want to package as a persistent agent. Triggers on phrases like \"create an agent that...\", \"build me a code reviewer\", \"make an agent for X\", \"edit the X agent\", \"clone the X agent and tweak it\". Builds 4-file persona bundles (IDENTITY\u002FEXPERTISE\u002FSOUL\u002FUSER + agent.config.json) that the `smith` CLI installs across all three platforms. Uses `smith` for all filesystem and validation work — the skill itself only orchestrates.","https:\u002F\u002Fgithub.com\u002Feliharoun\u002Fagent-smith\u002Fblob\u002Fmain\u002Fskills\u002Fthe-architect\u002FSKILL.md",[],[]]