
han-plugin-builder
Guidance for building Claude Code skills, agents, and plugins. The guidance skill answers authoring questions and, run with init, vendors the full guidance set into a repo as a path-scoped rule index so the right guidance surfaces while editing skill and agent files. Opt-in and dependency-free: installed on its own, not pulled in by the han meta-plugin.
- version
- 2.2.1
- GitHub stars
- 352
Install
/plugin install han-plugin-builder@hanRun it inside Claude Code after adding the marketplace with /plugin marketplace add testdouble/han.
Contents
Discovered from sourceSkills 3
Project Context
- personal config directory: !
bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude" - project .han/config.md: !
cat .han/config.md 2>/dev/null || echo ""
As your first action, use the Read tool on .han/config.md inside the personal config directory path above. A read
that returns no file is no personal configuration: continue silently. When that file or the project .han/config.md
probe supplies content, apply it per config-rule.md, which governs precedence
between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.
Guidance Location
The authoritative agent-authoring guidance ships in this plugin. Read the specific document a decision needs, when that decision is on the table — never read them all up front, because that defeats progressive disclosure and burns context on guidance the current agent does not touch.
- Plugin-building guidance root:
${CLAUDE_PLUGIN_ROOT}/skills/guidance/references/ - Agent-specific guidance:
${CLAUDE_PLUGIN_ROOT}/skills/guidance/references/agent-building-guidelines/
Map from decision to governing document (read just-in-time):
| Decision on the table | Read |
|---|---|
| Agent vs. skill vs. hook; one role (generate or evaluate) | plugin-entity-taxonomy.md, agent-building-guidelines/agent-domain-focus.md |
| Domain focus, vocabulary, role identity, anti-patterns | agent-building-guidelines/agent-domain-focus.md |
The description field (four components, boundaries, length) | agent-building-guidelines/agent-description-length.md, skill-building-guidance/skill-description-frontmatter.md |
Model tier (opus / sonnet / haiku / inherit) | agent-building-guidelines/agent-model-selection.md, specialization-and-model-selection.md |
| Self-containment — no references, scripts, or context injection | agent-building-guidelines/agent-external-files.md |
| Which frontmatter fields are valid (and which plugins ignore) | agent-building-guidelines/agent-external-files.md |
| Degraded environments (no git, missing tools) | agent-building-guidelines/graceful-degradation.md |
| Whether this agent is justified at all; how it gets dispatched | agent-building-guidelines/multi-agent-economics.md, skill-building-guidance/agent-dispatch-namespacing.md |
| New plugin needed (plugin.json, marketplace.json) | claude-marketplace-and-plugin-configuration/ and templates/ |
Operating Principles
- Interview relentlessly, but explore first. Interview the user relentlessly about every aspect of the agent until you reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. If a question can be answered by exploring the repository — the target plugin's existing agents, sibling descriptions, the skills that would dispatch this agent, conventions, the guidance documents above — explore instead of asking. Only surface questions that genuinely require the user's judgment.
- Ask one question at a time. Never batch questions. Settle one decision, let its answer resolve dependent decisions, then ask the next. Later answers routinely make earlier questions moot.
- Recommend, then ask. For every question surfaced to the user, provide a recommended answer with rationale grounded in evidence (existing agents, conventions, the guidance, the user's stated goal). The user can accept, amend, or redirect.
- Apply guidance as you go, then verify at the end. Consult the governing document when a decision is on the table (Step 4), and run a full guidance-conformance pass over the finished agent at the end (Step 6). The interview gets each decision approximately right; the review pass makes the artifact correct.
- An agent is self-contained. Unlike a skill, an agent is a single flat
.mdfile. Noreferences/folder, noscripts/folder, no!`command`context injection. Everything the agent needs is inlined in its body.
Build an Agent
Step 1: Capture the Request and Confirm It Is an Agent
Read the user's argument and the conversation to extract what the agent should do. If the request is too thin to start (for example, just "build an agent"), ask the user for one or two sentences on the agent's domain and what it produces — nothing else yet.
Confirm the entity type before anything else. Read
${CLAUDE_PLUGIN_ROOT}/skills/guidance/references/plugin-entity-taxonomy.md and apply its decision heuristic. An agent
is the thinking layer: it applies contextual judgment, taste, and discernment ("Does this require reasoning about
context?" → agent). If the work is a deterministic, flowchartable process, it is a skill — stop and recommend
skill-builder. If it fires automatically on an event, it is a hook.
Confirm the single role. An agent generates or evaluates, never both, because self-evaluation bias means the
reasoning that created a blind spot also rates it as correct (agent-domain-focus.md). If the request bundles
generation and evaluation, recommend splitting it into a generator agent and a separate evaluator agent. Only proceed
once an agent — with one role — is the right entity.
Step 2: Discover Before Asking
Locate the target plugin and learn its conventions before asking the user anything beyond the framing. Use Glob, Grep,
and find to gather:
- The target plugin directory and its
.claude-plugin/plugin.json. Confirm the plugin actually ships agents (anagents/directory) or is the right home for the first one. If the user has not said which plugin, infer candidates and confirm in Step 4. - Sibling agents in that plugin (
{plugin}/agents/*.md) — their descriptions, role identities, model tiers, domain vocabulary, and the boundaries they draw. A new agent's description must disambiguate against near-sibling agents in both directions. - The skills that would dispatch this agent. An agent is dispatched by a skill via the
Agenttool using the qualifieddefining-plugin:agent-name. Knowing the caller tells you what the agent receives and returns. - Whether any step depends on a tool (git, a CLI) that may be absent at dispatch time, which drives graceful-degradation wording.
Record what was found (file paths) and what was not.
Step 3: Build the Design Tree
Enumerate the decisions the agent needs, in dependency order. Resolve foundational decisions before dependent ones; never ask a dependent question before its parent is settled.
- Foundational — Which plugin owns it? What is the single narrow domain? Generate or evaluate? What does the agent produce, and who dispatches it?
- Identity — What is the Role Identity, the opening "You are a..." paragraph (under 50 tokens, domain + task + perspective, no flattery)? What 15-30 domain-vocabulary terms pass the 15-year-practitioner test? What 5-10 named anti-patterns with detection signals does the agent hunt for?
- Triggering — What does the
descriptionsay across all four components (what, when, boundary, breadth), and how does it disambiguate against near-sibling agents in both directions, within 1024 characters? - Capabilities — What model tier fits the cognitive load (
opusfor synthesis and judgment,sonnetfor structured procedures,haikufor fast lookups,inheritonly when matching the session is intentional)? Whattoolsdoes it need, defaulting to noAgenttool, since dispatch flows from skills to agents, and carrying it only when the agent's own protocol dispatches sub-agents? - Body structure — What inlined protocol, checklist, and reference content does the agent need to do its job, given it cannot use external files? Where does graceful-degradation wording belong?
Keep each node a concrete decision with a candidate answer. Do not pre-fill the tree with content the user has not confirmed.
Step 4: Interview Loop — One Branch at a Time
For each decision in dependency order:
- Try to resolve it from evidence. Re-check the target plugin, sibling agents, calling skills, conventions, and the governing guidance document for this decision (see the map above). If the evidence answers it, record the decision with its evidence and move on — do not ask.
- If evidence is insufficient, draft a recommended answer grounded in the guidance and the evidence available. Read the governing document first so the recommendation is correct, not improvised.
- Surface one question to the user, with the recommendation, the rationale, and the alternatives. State what changes depending on the answer. Wait for the answer before asking anything else.
- Descend. Once a decision is settled, re-evaluate which dependent decisions the new answer resolves, and continue.
Keep the interview moving — do not stall on questions the evidence can answer, and do not batch.
Step 5: Write the Agent
Write the single self-contained file:
- Create
{plugin}/agents/if it does not exist (usemkdir), then write{plugin}/agents/{agent-name}.md. The file is flat — no per-agent subdirectory, no companion folders. - Frontmatter:
name, thedescriptionsettled in the interview,tools(the allowlist — agents usetools, notallowed-tools), andmodel. Add other supported fields (disallowedTools,maxTurns,color, and so on) only when a decision called for them. Do not rely onhooks,mcpServers, orpermissionMode— Claude Code ignores all three on plugin agents as a security boundary. No XML angle brackets in any frontmatter value. - Body, in order: the Role Identity paragraph (under 50 tokens), then the
## Domain Vocabularysection, the## Anti-Patternssection, and the inlined protocol or checklist the agent follows. Embed reasoning in constraints. Add graceful-degradation wording ("If {tool} is not available, skip this step and note the limitation") to any tool-dependent step. No flattery, superlatives, or motivational framing — let domain vocabulary do the routing. - If the agent belongs in a brand-new plugin, create the plugin scaffold per the
claude-marketplace-and-plugin-configuration/guidance andtemplates/.
Step 6: Full Guidance-Conformance Review
This is the review pass the skill commits to. Re-read each governing document that applies to what you built and verify the finished agent against it, applying every fix directly. Do not summarize problems for the user without fixing them. Cover at minimum:
- Entity fit and single role (
plugin-entity-taxonomy.md,agent-building-guidelines/agent-domain-focus.md) — the agent is genuinely a judgment layer, targets one narrow domain, and only generates or only evaluates. - Role Identity (
agent-domain-focus.md) — the opening paragraph is under 50 tokens, states domain + task + perspective, and carries no flattery or motivational filler. - Domain vocabulary and anti-patterns (
agent-domain-focus.md) — 15-30 precise terms that pass the 15-year-practitioner test, and 5-10 named anti-patterns each with a detection signal, both inlined in the body. - Description (
agent-description-length.md,skill-description-frontmatter.md) — covers what, when, boundary, and trigger breadth; names near-sibling agents in boundary clauses; disambiguates in both directions (repair the sibling's description if a one-way gap exists); within 1024 characters, with domain vocabulary and anti-patterns kept in the body, not the description. - Model selection (
agent-model-selection.md,specialization-and-model-selection.md) —modelis set explicitly and matches the cognitive load, chosen on capability and not on cost. - Self-containment (
agent-external-files.md) — noreferences/orscripts/folder, no!`command`context injection; all protocol and reference content is inlined; frontmatter usestools(notallowed-tools), and the file relies on no field plugins ignore. - Tool set (
agent-dispatch-namespacing.md,agent-external-files.md) — the agent defaults to noAgenttool, since dispatch flows from skills to agents; it carries theAgenttool only when its own protocol dispatches sub-agents. Thetoolsallowlist is the minimum the work needs, each tool present only if the body uses it. - Graceful degradation (
agent-building-guidelines/graceful-degradation.md) — every tool-dependent step checks availability inline and notes the limitation when the tool is absent. - Economic justification (
multi-agent-economics.md) — the agent clears the bar for existing: a single well-prompted agent or an instruction improvement to an existing agent would not do the job as well.
Apply the YAGNI discipline throughout: vocabulary terms, anti-patterns, tools, and frontmatter fields must each earn their place against the agent's actual job. Cut anything added "for completeness."
Step 7: Present and Hand Off
Summarize for the user:
- The agent file written (path) and its shape (role, model, tools, vocabulary and anti-pattern counts).
- The decisions settled by evidence versus by user input.
- The fixes the Step 6 review applied, citing the guidance document behind each.
- How the agent is dispatched: the qualified
defining-plugin:agent-nameand which skill (existing or to-be-built) would call it. If a calling skill is needed and does not exist, recommendskill-builder.
Note that plugin entities rarely land in one pass: per iterative-plugin-development.md, plan for 3-5 iterations. Ask
whether the user wants to iterate on the agent's domain framing or considers it ready to test.
Project Context
- personal config directory: !
bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude" - project .han/config.md: !
cat .han/config.md 2>/dev/null || echo ""
As your first action, use the Read tool on .han/config.md inside the personal config directory path above. A read
that returns no file is no personal configuration: continue silently. When that file or the project .han/config.md
probe supplies content, apply it per config-rule.md, which governs precedence
between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.
This skill has three modes. Pick the mode from how it was invoked, then follow only that mode's steps.
- If the invocation argument is
initorinitialize(any case), run Initialization Mode. - If the invocation argument is
updateorrefresh(any case), run Update Mode. - Otherwise, run Guidance Mode.
Guidance Mode
Serve the relevant guidance for what the user is building. Do not read every guidance document — that defeats the purpose. Find the one or two that apply, read them, and apply them.
The guidance documents live in this skill's own references/ directory. Use this map to choose, then read only the
specific file(s) you need:
- Deciding whether something should be a skill, agent, or hook →
${CLAUDE_SKILL_DIR}/references/plugin-entity-taxonomy.md. - Authoring or hardening a skill (descriptions, frontmatter, progressive disclosure, allowed-tools, scripts,
composition, testing, troubleshooting) → the files under
${CLAUDE_SKILL_DIR}/references/skill-building-guidance/. - Authoring an agent (domain focus, self-containment, model selection, multi-agent economics, graceful degradation) →
the files under
${CLAUDE_SKILL_DIR}/references/agent-building-guidelines/. - Plugin or marketplace configuration files (plugin.json, marketplace.json, monitors.json, themes.json) → the files
under
${CLAUDE_SKILL_DIR}/references/claude-marketplace-and-plugin-configuration/. - Versioning, README structure, local development, the iterative development process, and
specialization-versus-model-tier reasoning → the top-level files in
${CLAUDE_SKILL_DIR}/references/. - Writing the instructions for a target model (how Sonnet 5, Opus 5, and Fable 5 differ in following instructions, which
instructions to leave out, and how to calibrate length, narration, and scope) →
${CLAUDE_SKILL_DIR}/references/per-model-authoring.md. - Copyable starter files →
${CLAUDE_SKILL_DIR}/references/templates/.
Steps:
- Identify what the user is building or asking about.
- List the relevant subdirectory under
${CLAUDE_SKILL_DIR}/references/to see the available documents, using the map above. - Read only the document(s) that directly apply.
- Apply the guidance to the user's situation. Cite the document you used so the user can read it in full if they want.
Initialization Mode
Install the plugin-building skills into the current repository so anyone using the repo can run them and consult the guidance, with no dependency on this plugin remaining installed.
- Run
${CLAUDE_SKILL_DIR}/scripts/init-guidance.shfrom the repository root. The script vendors three skills into.claude/skills/under aplugin-prefix so they never collide with this plugin's own slash commands: a guidance-onlyplugin-guidanceskill (whosereferences/directory is the single in-repo copy of the guidance documents),plugin-skill-builder, andplugin-agent-builder(with their names, cross-references, and guidance paths rewritten to that vendored copy). It then writes the path-scoped rule index at.claude/rules/plugin-building-guidance.md. Capture its output. - Report to the user what was written: the three vendored skills, the total file count, the rule index path, and the
paths:globs. Explain that the three skills are now available directly in the repo (/plugin-guidance,/plugin-skill-builder,/plugin-agent-builder) and that the rule index is an index only — Claude Code loads it when a matching skill or agent file is touched, and it points to the vendored guidance so only the documents the current file needs are loaded, not all of them. - Do not commit. Leave the new files staged for the user to review.
Update Mode
Refresh the vendored skills and their rule index in a repository that already has them, so contributors get the current
skills and guidance after this plugin has been updated. Updating is the same vendoring operation as Initialization Mode
— it replaces every vendored skill in full (each SKILL.md and the guidance documents under
plugin-guidance/references/, removing any files that the plugin source has since dropped) and regenerates the rule
index — but it first confirms the skills are actually installed before touching anything.
- Check whether the skills are already installed at the expected location. Run
find .claude -maxdepth 3 \( -path '*/skills/plugin-guidance' -o -name plugin-building-guidance.md \)from the repository root. The skills are installed only when both the.claude/skills/plugin-guidancedirectory and the.claude/rules/plugin-building-guidance.mdrule index turn up. - If the skills are not installed (the
findturns up neither, or only one of the two), do not update. Tell the user the skills are not installed at the expected location (.claude/skills/plugin-guidance/and.claude/rules/plugin-building-guidance.md) and ask whether they want to install them now. If they confirm, switch to Initialization Mode and run its steps. If they decline, stop without writing anything. - If the skills are installed, run
${CLAUDE_SKILL_DIR}/scripts/init-guidance.shfrom the repository root. The script removes each vendored skill directory and re-copies it fresh from the plugin source, so everySKILL.mdand every guidance document underplugin-guidance/references/is replaced with the current version (and any file the plugin has since removed is dropped), then regenerates the rule index at.claude/rules/plugin-building-guidance.md. Capture its output. - Report to the user what was refreshed: the three vendored skills, the total file count, the rule index path, and the
paths:globs. - Do not commit. Leave the changes staged for the user to review.
Project Context
- personal config directory: !
bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude" - project .han/config.md: !
cat .han/config.md 2>/dev/null || echo ""
As your first action, use the Read tool on .han/config.md inside the personal config directory path above. A read
that returns no file is no personal configuration: continue silently. When that file or the project .han/config.md
probe supplies content, apply it per config-rule.md, which governs precedence
between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.
Guidance Location
The authoritative skill-authoring guidance ships in this plugin. Read the specific document a decision needs, when that decision is on the table — never read them all up front, because that defeats progressive disclosure and burns context on guidance the current skill does not touch.
- Plugin-building guidance root:
${CLAUDE_PLUGIN_ROOT}/skills/guidance/references/ - Skill-specific guidance:
${CLAUDE_PLUGIN_ROOT}/skills/guidance/references/skill-building-guidance/
Map from decision to governing document (read just-in-time):
| Decision on the table | Read |
|---|---|
| Skill vs. agent vs. hook | plugin-entity-taxonomy.md |
| Use cases, trigger phrases, test cases | skill-building-guidance/use-case-planning.md |
| Directory name, file name, dependency prefix | skill-building-guidance/naming-conventions.md |
The description field (four components, boundaries) | skill-building-guidance/skill-description-frontmatter.md, skill-building-guidance/skill-description-length.md |
| Which frontmatter fields to set | skill-building-guidance/skill-frontmatter-fields.md |
| Where content lives (body vs. references vs. scripts vs. assets) | skill-building-guidance/progressive-disclosure.md, skill-building-guidance/skill-reference-files.md |
| Step structure and workflow shape | skill-building-guidance/workflow-patterns.md, skill-building-guidance/writing-effective-instructions.md |
allowed-tools, Bash permission granularity | skill-building-guidance/allowed-tools-bash-permissions.md, skill-building-guidance/allowed-tools-AskUserQuestion.md |
| Reading config / runtime data | skill-building-guidance/context-injection-commands.md, skill-building-guidance/dynamic-project-discovery.md |
| Running scripts | skill-building-guidance/script-execution-instructions.md |
| Dispatching agents from the skill | skill-building-guidance/agent-dispatch-namespacing.md, plus agent-building-guidelines/multi-agent-economics.md |
| Degraded environments (no git, missing tools) | skill-building-guidance/graceful-degradation.md, skill-building-guidance/optional-git-repositories.md |
| Frontmatter safety (angle brackets, YAML types) | skill-building-guidance/security-restrictions.md |
| Hardening fuzzy steps into deterministic ones | skill-building-guidance/hardening-fuzzy-vs-deterministic.md |
| Splitting or composing skills | skill-building-guidance/skill-decomposition.md, skill-building-guidance/skill-composition.md |
| Defining success and tests | skill-building-guidance/success-criteria-and-testing.md |
| New plugin needed (plugin.json, marketplace.json) | claude-marketplace-and-plugin-configuration/ and templates/ |
Operating Principles
- Interview relentlessly, but explore first. Interview the user relentlessly about every aspect of the skill until
you reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions
one-by-one. If a question can be answered by exploring the repository — the target plugin's existing skills, sibling
descriptions,
plugin.json, conventions, the guidance documents above — explore instead of asking. Only surface questions that genuinely require the user's judgment. - Ask one question at a time. Never batch questions. Settle one decision, let its answer resolve dependent decisions, then ask the next. Later answers routinely make earlier questions moot.
- Recommend, then ask. For every question surfaced to the user, provide a recommended answer with rationale grounded in evidence (existing skills, conventions, the guidance, the user's stated goal). The user can accept, amend, or redirect.
- Apply guidance as you go, then verify at the end. Consult the governing document when a decision is on the table (Step 4), and run a full guidance-conformance pass over the finished files at the end (Step 6). The interview gets each decision approximately right; the review pass makes the artifact correct.
Build a Skill
Step 1: Capture the Request and Confirm It Is a Skill
Read the user's argument and the conversation to extract what the skill should do. If the request is too thin to start (for example, just "build a skill"), ask the user for one or two sentences on what the skill should accomplish and what triggers it — nothing else yet.
Confirm the entity type before anything else. Read
${CLAUDE_PLUGIN_ROOT}/skills/guidance/references/plugin-entity-taxonomy.md and apply its decision heuristic. A skill
is a deterministic, flowchartable process ("Can I flowchart every path?" → skill). If the work is really contextual
judgment with no fixed flowchart, it is an agent — stop and recommend agent-builder. If it fires automatically on an
event, it is a hook. If the request bundles a deterministic process and a judgment layer, recommend building them
separately and composing them. Only proceed once a skill is the right entity.
Step 2: Discover Before Asking
Locate the target plugin and learn its conventions before asking the user anything beyond the framing. Use Glob, Grep,
and find to gather:
- The target plugin directory and its
.claude-plugin/plugin.json(name, description, version). If the user has not said which plugin, infer candidates from the repository and confirm the target in Step 4. - Sibling skills in that plugin (
{plugin}/skills/*/SKILL.md) — their descriptions, frontmatter, step structure, and the trigger space they already own. New descriptions must disambiguate against these siblings in both directions. CLAUDE.md,AGENTS.md, and anyproject-discovery.md— repository conventions, the documentation root, and how skills are catalogued.- Whether the skill needs an external tool (gh, jq, an MCP server). External dependencies drive the directory-name
prefix and a
descriptionmention.
Record what was found (file paths) and what was not. A missing convention is itself a finding that shapes the skill.
Step 3: Build the Design Tree
Enumerate the decisions the skill needs, in dependency order. Resolve foundational decisions before dependent ones; never ask a dependent question before its parent is settled.
- Foundational — Which plugin owns it? What are the 2-3 concrete use cases (trigger phrase, workflow, tools, domain
knowledge) per
use-case-planning.md? What artifact or outcome does each use case produce? - Identity — What is the directory name (which becomes the slash command)? Does it follow the gerund/process-name
and dependency-prefix rules? What does the
descriptionsay across all four components (what, when, boundary, breadth), and how does it disambiguate against siblings in both directions? - Workflow — Which workflow pattern fits (sequential, iterative, context-aware, domain-specific, or a combination)? What are the numbered steps? Where do human gates belong (before irreversible or outward-facing actions only)?
- Capabilities — What
allowed-toolsdoes each step need, at the right Bash granularity? Does the skill dispatch agents (and are they available in this plugin)? Does it run scripts? Does it read runtime config via context injection? - Layout — What belongs in the SKILL.md body (process), in
references/(templates, checklists, domain knowledge), inscripts/(deterministic operations), and inassets/(output files)? What other frontmatter fields apply (argument-hint,arguments,model,paths)?
Keep each node a concrete decision with a candidate answer. Do not pre-fill the tree with content the user has not confirmed.
Step 4: Interview Loop — One Branch at a Time
For each decision in dependency order:
- Try to resolve it from evidence. Re-check the target plugin, sibling skills, conventions, and the governing guidance document for this decision (see the map above). If the evidence answers it, record the decision with its evidence and move on — do not ask.
- If evidence is insufficient, draft a recommended answer grounded in the guidance and the evidence available. Read the governing document first so the recommendation is correct, not improvised.
- Surface one question to the user, with the recommendation, the rationale, and the alternatives. State what changes depending on the answer. Wait for the answer before asking anything else.
- Descend. Once a decision is settled, re-evaluate which dependent decisions the new answer resolves, and continue.
Keep the interview moving — do not stall on questions the evidence can answer, and do not batch.
Step 5: Write the Skill
Create the skill directory and write the files:
- Create
{plugin}/skills/{skill-name}/(usemkdir). The directory name is the slash command and must match the frontmattername. - Write
SKILL.mdwith:- Frontmatter:
name(matching the directory), thedescriptionsettled in the interview,allowed-tools, and any other settled fields. Never putAskUserQuestioninallowed-tools. No XML angle brackets in any frontmatter value. - A body of numbered process steps following the chosen workflow pattern. Be specific and actionable, embed reasoning
in constraints (
Always/Never X BECAUSE Y), include error handling for tool-dependent steps, and reference any bundled resource by exact path.
- Frontmatter:
- Create
references/,scripts/, orassets/and their files only if a use case needs them. Domain knowledge (templates, checklists, matrices) goes inreferences/; deterministic operations go inscripts/; output-only files go inassets/. Do not create empty or speculative folders. - If the skill belongs in a brand-new plugin, create the plugin scaffold (
.claude-plugin/plugin.json, and a marketplace entry if the repo uses one) per theclaude-marketplace-and-plugin-configuration/guidance and thetemplates/.
Step 6: Full Guidance-Conformance Review
This is the review pass the skill commits to. Re-read each governing document that applies to what you built and verify the finished files against it, applying every fix directly. Do not summarize problems for the user without fixing them. Cover at minimum:
- Entity fit (
plugin-entity-taxonomy.md) — the skill is genuinely a flowchartable process, not a judgment layer that should be an agent. - Description (
skill-description-frontmatter.md,skill-description-length.md) — third person; covers what, when, boundary, and trigger breadth; weaves trigger words into prose rather than appending a keyword list; names sibling skills in boundary clauses; disambiguates in both directions (update the sibling's description if a one-way gap exists); within 1024 characters. - Naming (
naming-conventions.md) — directory name matchesname, is a process/gerund name when the output is a plan or doc, carries a dependency prefix when an external tool is required, noREADME.mdin the skill folder,SKILL.mdcased exactly. - Progressive disclosure (
progressive-disclosure.md,skill-reference-files.md) — body is process only and under 500 lines; domain knowledge is inreferences/; scripts hold deterministic work; nothing the toolchain already enforces is restated; every reference file is linked directly from SKILL.md rather than only through another reference file, every reference link stays inside the plugin directory, and any reference file over roughly 100 lines opens with a## Contentslist unless it is a template copied whole into output. - Instruction quality (
writing-effective-instructions.md,workflow-patterns.md) — steps are specific and actionable; constraints embed reasoning; error handling is present; human gates sit only at irreversible actions; the most critical item in each list is placed last. - Tools and safety (
allowed-tools-bash-permissions.md,allowed-tools-AskUserQuestion.md,security-restrictions.md) — Bash permissions are scoped correctly with separate entries;AskUserQuestionis absent fromallowed-tools; no angle brackets or non-standard YAML in frontmatter. - Discovery and degradation (
dynamic-project-discovery.md,graceful-degradation.md,optional-git-repositories.md) — the skill discovers project specifics dynamically rather than hardcoding them, and degrades gracefully when a tool or git is absent, where relevant. - Dispatch (
agent-dispatch-namespacing.md) — if the skill dispatches agents, every dispatch uses the qualifieddefining-plugin:agent-name, and the agents actually exist in an installed plugin. - Tests (
success-criteria-and-testing.md) — each use case maps to a triggering and functional test the user can run.
Apply the YAGNI discipline throughout: every step, reference file, tool permission, and frontmatter field must earn its place against a real use case. Cut anything added "for completeness" or "for future flexibility."
Step 7: Present and Hand Off
Summarize for the user:
- The files written (paths), and what each contains.
- The decisions settled by evidence versus by user input.
- The fixes the Step 6 review applied, citing the guidance document behind each.
- The triggering and functional tests derived from the use cases, so the user can validate the skill against the model tier it targets.
Note that plugin entities rarely land in one pass: per iterative-plugin-development.md, plan for 3-5 iterations. Ask
whether the user wants to iterate on specific steps or considers the skill ready to test.
Sponsors
Details
- Marketplace
- testdouble/han
- Source
- han-plugin-builder
- Category
- Community