| name | the-keymaker |
| description | 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.). |
| metadata | {"author":"eliharoun"} |
The Keymaker
A 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 open standard and works across OpenCode, Claude Code, Codex, and any other framework that adopts it.
Core principle
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:
- Discoverable — a description that triggers reliably
- Scannable — clear structure, quick reference tables
- Bulletproof — explanations that resist rationalization
- Validated — passes
scripts/validate-skill.sh before shipping
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.
When to use this skill
Trigger when the user says any of:
- "Create a skill for…" / "Turn this workflow into a skill"
- "Improve / edit / fix the X skill"
- "My skill isn't triggering" / "the agent ignores my skill"
- "Validate this skill" / "is this SKILL.md valid?"
- "How do I write a skill?"
- "Package this as a skill"
Also trigger proactively when the user describes a multi-step workflow they keep repeating across sessions or projects — that's a skill waiting to happen.
The workflow
RED Phase 1 — Capture intent + run baseline (agent without skill)
Phase 2 — Choose structural approach
GREEN Phase 3 — Draft SKILL.md (+ optional bundled files)
GATE Phase 4 — Validate (HARD GATE: validator must pass)
REFACTOR Phase 5 — Sanity-test with realistic prompts; iterate
DEPLOY Phase 6 — Place in correct directory; smoke test
Use 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.
Phase 1 — RED: Capture intent and baseline
1a. Interview the user
Ask 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.
- Purpose. What should this skill enable the agent to do? (one or two sentences)
- Triggers. When should it trigger? List user phrases, file types, error symptoms, situations.
- Type. Is this a discipline skill (a rule/process), a technique (how-to), a pattern (mental model), or a reference (docs/API)? This determines testing strategy.
- Bundled resources. Will this need scripts, references, or assets, or is a single SKILL.md enough?
- Target directory. Where should it live? Default:
skills/<name>/ in the current repo. Never under ~/.claude/, ~/.config/opencode/, or ~/.agents/ — those are install paths.
For workflows the user already demonstrated in conversation, extract the candidate steps, tools used, corrections made, and input/output 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.
1b. Run the baseline
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:
- What did the agent do?
- What rationalizations did it use? ("This is just a simple…", "I'll skip this because…")
- Which prompts triggered the worst behavior?
If the agent already does the right thing without your skill, stop. You don't need a skill — the model already handles it.
Save baseline notes; you will use them in Phase 3 to target your skill at specific observed failures, not hypothetical ones.
Phase 2 — Choose a structural approach
Pick the structure based on Phase 1 answers. Recommend one, confirm with the user.
| Structure | Best for | Layout |
|---|
| Single-file | Skills under ~300 lines of total content | Just SKILL.md |
| SKILL.md + references/ | Total content > ~300 lines, or distinct sub-domains | SKILL.md (workflow) + references/<topic>.md (detail) |
| Workflow-based | Multi-step procedures | SKILL.md is a phase sequence; one reference per phase |
| Task-based | Tool collections / menu of operations | SKILL.md is a task index; one reference per task |
| Reference-based | Navigation skills, large knowledge bases | SKILL.md is a thin router; references hold the knowledge |
Whichever structure you pick, keep SKILL.md under 500 lines (validator hard limit) and aim for < 400 lines (validator warning).
Phase 3 — GREEN: Draft
3a. Scaffold
Use the bundled scaffolder to create the directory structure:
./scripts/scaffold-skill.sh <skill-name>
This creates <target>/<skill-name>/ with SKILL.md (from template), scripts/, and references/. It refuses to write into install paths (~/.claude/, ~/.config/opencode/, ~/.agents/).
3b. Write the frontmatter
---
name: skill-name-with-hyphens
description: Use when [specific triggering conditions, symptoms, contexts]
license: MIT
---
Required: name, description. Everything else is optional.
name rules (validator-enforced):
- 1–64 characters
- Lowercase alphanumeric with single hyphens (
^[a-z0-9]+(-[a-z0-9]+)*$)
- Must match the directory name exactly
description rules:
- 1–1024 characters total
- Written in third person, starts with "Use when…"
- 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
When drafting or revising the description, read references/writing-effective-descriptions.md. The four principles + before/after rewrites in that file are the difference between a skill that triggers and one that sits dormant.
For client-specific frontmatter fields (disable-model-invocation, allowed-tools, paths, etc.), read references/frontmatter-reference.md. It's a 14-field × 4-client matrix — load it when you need anything beyond name + description.
3c. Write the body
Use this skeleton as a starting point; adapt to skill type:
# Skill Name
## Overview
What this is, in 1–2 sentences. State the core principle.
## When to use this skill
Bulleted symptoms / triggers (mirrors and expands the description).
"Do NOT use when…" clauses for adjacent-but-different cases.
## Core concepts (optional)
2–5 domain ideas the agent needs before executing. Skip if self-explanatory.
## Workflow / The pattern
The actual technique. Inline code for short examples; link to a file for long ones.
## Quick reference
Table or short bullets for the most common operations. Optimize for scanning.
## Common mistakes
What goes wrong + how to fix it. Pulled directly from baseline observations.
## Gotchas (optional)
Non-obvious facts that defy reasonable assumptions. Often the highest-value section.
## Red flags (for discipline skills)
Thoughts that mean STOP — the agent is rationalizing.
3d. Writing principles
- Imperative voice. "Run the baseline." Not "You should consider running…"
- Explain WHY, not just WHAT. Modern LLMs have good theory of mind. A two-sentence rationale beats five
MUSTs.
- One excellent example beats five mediocre ones. Don't port to multiple languages. Pick the most relevant language; agents port well on demand.
- Procedures over declarations. General approaches the agent can apply, not specific one-off answers.
- Keywords for discoverability. Sprinkle the words an agent would search for: error messages, library names, symptoms, synonyms.
- No narrative storytelling. "In session 2025-04-30 we discovered…" is wrong. Skills are reference material, not war stories.
- Cross-reference, don't duplicate. Link to other skills by name. Never
@-link or force-load other skills' content — it burns context.
- Address baseline failures specifically. For each rationalization observed in Phase 1b, add an explicit counter — not generic discipline.
3e. Bundled scripts
Add scripts to scripts/ 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/script-guidelines.md for portability rules (no jq, cross-platform sed, executable bit, etc.) and templates.
Every 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.
Phase 4 — GATE: Validate
This is a hard gate. Run the validator against the new skill:
./scripts/validate-skill.sh <path-to-skill-dir-or-SKILL.md>
The validator runs 15 checks across structure, frontmatter, body, supporting files, and safety. Any ❌ blocks progression. Common failures and fixes:
| Error | Fix |
|---|
name does not match directory | Rename either the directory or the frontmatter field so they agree |
description is N chars; must be 1-1024 | Tighten the description; move details to body |
body is N lines; must be ≤ 500 | Extract content into references/<topic>.md |
referenced script not executable | chmod +x scripts/<name>.sh |
referenced file missing | Create the file or remove the reference |
broken markdown link | Fix the path or remove the link |
possible secret detected in body | Remove the secret; use a placeholder or env var |
first body line must be an H1 heading | Add # Skill Name after the closing --- |
Fix every ❌ and re-run until exit code is 0. Warnings (⚠️) are advisory but worth addressing.
scripts/validate-skill.sh
Validates a SKILL.md against the Agent Skills spec.
When to use: Phase 4 (gate), after every revision in Phase 5, and before commit.
Usage: ./scripts/validate-skill.sh <path-to-SKILL.md-or-skill-dir>
Output: line-per-check with ✅/⚠️/❌ icons, summary line at the end. Exit 0 on pass (warnings allowed), 1 on error, 2 on usage failure.
scripts/scaffold-skill.sh
Creates a new skill directory from the template.
When to use: Phase 3a, to create a new skill skeleton.
Usage: ./scripts/scaffold-skill.sh [-y] <skill-name> [target-parent-dir]
Output: creates <target>/<skill-name>/ with SKILL.md, scripts/, references/. Refuses to write under agent install paths.
Phase 5 — REFACTOR: Sanity-test and iterate
5a. Generate test prompts
Save 2–3 realistic test prompts to <skill>/evals.json using assets/evals.json.template. Each prompt should be something a real user would plausibly type, varying in phrasing and explicitness.
5b. Run them
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.
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.
For discipline skills, combine pressures (time + sunk cost + authority + exhaustion) — that's where loopholes hide.
5c. Iterate based on feedback
Four guiding principles:
- 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.
- Keep the body lean. Remove instructions that aren't pulling their weight. Unnecessary prose competes for the agent's attention.
- Explain the why. Reframe heavy-handed
MUST directives into reasoned guidance. LLMs follow well-explained whys more reliably than blunt mandates.
- Extract reusable scripts. If multiple test runs caused the agent to write the same helper, bundle it in
scripts/ once.
For 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.
Phase 6 — DEPLOY: Place and smoke-test
6a. Place the skill
| Platform | Project (per-repo) | Global (per-user) |
|---|
| OpenCode | .opencode/skills/<name>/SKILL.md | ~/.config/opencode/skills/<name>/SKILL.md |
| Claude Code | .claude/skills/<name>/SKILL.md | ~/.claude/skills/<name>/SKILL.md |
| Codex | .agents/skills/<name>/SKILL.md | ~/.agents/skills/<name>/SKILL.md |
Cross-platform tip: OpenCode reads from all three project paths and the matching global paths. Placing your skill under .claude/skills/ makes it usable by both Claude Code and OpenCode without duplication.
Always edit in your source repo and symlink (or copy) into install paths. Never edit SKILL.md files inside ~/.claude/ or ~/.config/opencode/ directly — they're consumption locations and may be overwritten by package managers.
6b. Smoke-test
Open a fresh agent session. Verify:
- The skill appears in the agent's available skills list
- A natural-language prompt matching the description loads the skill
- The agent follows the skill's instructions
If the skill doesn't appear: check SKILL.md is uppercase, run the validator, ensure the directory name matches name.
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/writing-effective-descriptions.md for rewriting strategies.
Quick reference
| Task | Action |
|---|
| Create a new skill | Run all six phases. Don't skip the baseline. |
| Edit existing skill | Re-run baseline scenarios first to confirm the new behavior is needed. Re-validate after. |
| Skill not triggering | Description problem. Read references/writing-effective-descriptions.md. Add user's actual words. |
| Skill triggers too often | Description too broad. Add "Do NOT use when…" or split into two skills. |
| Long reference material | Move to references/<topic>.md, link from SKILL.md with a one-line "load when…" hint. |
| Reusable code logic | Put in scripts/, document in SKILL.md with usage block. |
| Need cross-client field info | references/frontmatter-reference.md |
| Need script portability rules | references/script-guidelines.md |
| Validate before committing | ./scripts/validate-skill.sh <path> |
| Scaffold a fresh skill | ./scripts/scaffold-skill.sh <name> |
Common mistakes
| Mistake | Fix |
|---|
| Description summarizes workflow | Rewrite as triggers only ("Use when X, Y, Z"). The body teaches the workflow. |
| Skill name has uppercase / underscores | Use lowercase + single hyphens only. The validator enforces this. |
Directory name ≠ name field | Make them identical. The validator enforces this. |
| Frontmatter > 1024 chars | Trim description; move details to body. |
| Multi-language code examples | Pick one language; the agent ports on demand. |
MUST / NEVER everywhere with no rationale | Replace with one-sentence explanations of why. |
| Skill written without baseline | Delete it. Run baseline. Start over. |
| Edited a skill without re-validating | An edit is a new skill. Re-run validator. |
| Forgot to document a bundled script | Add a script-doc block to SKILL.md. Without it, the agent ignores the script. |
Editing ~/.claude/skills/<name>/ directly | Edit in source repo. Symlink into install path. |
| Body grew past 400 lines | Extract sections into references/. The validator warns at 400, errors at 500. |
Red flags — STOP and start over
If you catch yourself thinking any of these, you are about to ship a bad skill:
- "I don't need to baseline, the failure is obvious"
- "This is just a small edit, no need to re-validate"
- "The description is fine, the agent will figure it out"
- "I'll add more examples instead of fixing the structure"
- "It works for me, ship it"
- "I know what the agent does without running it"
- "The validator's wrong about this one, I'll skip it"
All of these mean: run the baseline. Validate. Test. Then ship.
When NOT to create a skill
- The behavior is project-specific → put it in
CLAUDE.md / AGENTS.md / opencode.md instead
- It's a one-off solution → just do it inline
- It's a mechanical constraint enforceable by a linter or hook → automate it deterministically
- The agent already does the right thing without it (verified by baseline)
- It duplicates an existing skill → improve the existing one
The bottom line
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).
If you follow TDD for code, follow it for skills. Same discipline, different artifact — and a real validator standing between drafts and shipping.
Source: eliharoun/agent-smith — distributed by TomeVault.
