bash \"${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh\" 2>/dev/null || echo \"$HOME/.claude\"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\nthat returns no file is no personal configuration: continue silently. When that file or the project .han/config.md\nprobe supplies content, apply it per config-rule.md, which governs precedence\nbetween the two files, relative-path resolution, and what to do with a file that reads but cannot be used.
The authoritative skill-authoring guidance ships in this plugin. Read the specific document a decision needs, when that\ndecision is on the table — never read them all up front, because that defeats progressive disclosure and burns context\non guidance the current skill does not touch.
\n${CLAUDE_PLUGIN_ROOT}/skills/guidance/references/${CLAUDE_PLUGIN_ROOT}/skills/guidance/references/skill-building-guidance/Map from decision to governing document (read just-in-time):
\n| Decision on the table | \nRead | \n
|---|---|
| Skill vs. agent vs. hook | \nplugin-entity-taxonomy.md | \n
| Use cases, trigger phrases, test cases | \nskill-building-guidance/use-case-planning.md | \n
| Directory name, file name, dependency prefix | \nskill-building-guidance/naming-conventions.md | \n
The description field (four components, boundaries) | \nskill-building-guidance/skill-description-frontmatter.md, skill-building-guidance/skill-description-length.md | \n
| Which frontmatter fields to set | \nskill-building-guidance/skill-frontmatter-fields.md | \n
| Where content lives (body vs. references vs. scripts vs. assets) | \nskill-building-guidance/progressive-disclosure.md, skill-building-guidance/skill-reference-files.md | \n
| Step structure and workflow shape | \nskill-building-guidance/workflow-patterns.md, skill-building-guidance/writing-effective-instructions.md | \n
allowed-tools, Bash permission granularity | \nskill-building-guidance/allowed-tools-bash-permissions.md, skill-building-guidance/allowed-tools-AskUserQuestion.md | \n
| Reading config / runtime data | \nskill-building-guidance/context-injection-commands.md, skill-building-guidance/dynamic-project-discovery.md | \n
| Running scripts | \nskill-building-guidance/script-execution-instructions.md | \n
| Dispatching agents from the skill | \nskill-building-guidance/agent-dispatch-namespacing.md, plus agent-building-guidelines/multi-agent-economics.md | \n
| Degraded environments (no git, missing tools) | \nskill-building-guidance/graceful-degradation.md, skill-building-guidance/optional-git-repositories.md | \n
| Frontmatter safety (angle brackets, YAML types) | \nskill-building-guidance/security-restrictions.md | \n
| Hardening fuzzy steps into deterministic ones | \nskill-building-guidance/hardening-fuzzy-vs-deterministic.md | \n
| Splitting or composing skills | \nskill-building-guidance/skill-decomposition.md, skill-building-guidance/skill-composition.md | \n
| Defining success and tests | \nskill-building-guidance/success-criteria-and-testing.md | \n
| New plugin needed (plugin.json, marketplace.json) | \nclaude-marketplace-and-plugin-configuration/ and templates/ | \n
plugin.json, conventions, the guidance documents above — explore instead of asking. Only surface\nquestions that genuinely require the user's judgment.Read the user's argument and the conversation to extract what the skill should do. If the request is too thin to start\n(for example, just \"build a skill\"), ask the user for one or two sentences on what the skill should accomplish and what\ntriggers it — nothing else yet.
\nConfirm the entity type before anything else. Read\n${CLAUDE_PLUGIN_ROOT}/skills/guidance/references/plugin-entity-taxonomy.md and apply its decision heuristic. A skill\nis a deterministic, flowchartable process (\"Can I flowchart every path?\" → skill). If the work is really contextual\njudgment with no fixed flowchart, it is an agent — stop and recommend agent-builder. If it fires automatically on an\nevent, it is a hook. If the request bundles a deterministic process and a judgment layer, recommend building them\nseparately and composing them. Only proceed once a skill is the right entity.
Locate the target plugin and learn its conventions before asking the user anything beyond the framing. Use Glob, Grep,\nand find to gather:
.claude-plugin/plugin.json (name, description, version). If the user has not\nsaid which plugin, infer candidates from the repository and confirm the target in Step 4.{plugin}/skills/*/SKILL.md) — their descriptions, frontmatter, step structure, and\nthe trigger space they already own. New descriptions must disambiguate against these siblings in both directions.CLAUDE.md, AGENTS.md, and any project-discovery.md — repository conventions, the documentation root, and how\nskills are catalogued.description mention.Record what was found (file paths) and what was not. A missing convention is itself a finding that shapes the skill.
\nEnumerate the decisions the skill needs, in dependency order. Resolve foundational decisions before dependent ones;\nnever ask a dependent question before its parent is settled.
\nuse-case-planning.md? What artifact or outcome does each use case produce?description say across all four components (what, when, boundary,\nbreadth), and how does it disambiguate against siblings in both directions?allowed-tools does each step need, at the right Bash granularity? Does the skill dispatch\nagents (and are they available in this plugin)? Does it run scripts? Does it read runtime config via context\ninjection?references/ (templates, checklists, domain knowledge),\nin scripts/ (deterministic operations), and in assets/ (output files)? What other frontmatter fields apply\n(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\nconfirmed.
\nFor each decision in dependency order:
\nKeep the interview moving — do not stall on questions the evidence can answer, and do not batch.
\nCreate the skill directory and write the files:
\n{plugin}/skills/{skill-name}/ (use mkdir). The directory name is the slash command and must match the\nfrontmatter name.SKILL.md with:\nname (matching the directory), the description settled in the interview, allowed-tools, and any\nother settled fields. Never put AskUserQuestion in allowed-tools. No XML angle brackets in any frontmatter\nvalue.Always/Never X BECAUSE Y), include error handling for tool-dependent steps, and reference any\nbundled resource by exact path.references/, scripts/, or assets/ and their files only if a use case needs them. Domain knowledge\n(templates, checklists, matrices) goes in references/; deterministic operations go in scripts/; output-only files\ngo in assets/. Do not create empty or speculative folders..claude-plugin/plugin.json, and a\nmarketplace entry if the repo uses one) per the claude-marketplace-and-plugin-configuration/ guidance and the\ntemplates/.This is the review pass the skill commits to. Re-read each governing document that applies to what you built and verify\nthe finished files against it, applying every fix directly. Do not summarize problems for the user without fixing them.\nCover at minimum:
\nplugin-entity-taxonomy.md) — the skill is genuinely a flowchartable process, not a judgment layer\nthat should be an agent.skill-description-frontmatter.md, skill-description-length.md) — third person; covers what,\nwhen, boundary, and trigger breadth; weaves trigger words into prose rather than appending a keyword list; names\nsibling skills in boundary clauses; disambiguates in both directions (update the sibling's description if a one-way\ngap exists); within 1024 characters.naming-conventions.md) — directory name matches name, is a process/gerund name when the output is a\nplan or doc, carries a dependency prefix when an external tool is required, no README.md in the skill folder,\nSKILL.md cased exactly.progressive-disclosure.md, skill-reference-files.md) — body is process only and under\n500 lines; domain knowledge is in references/; scripts hold deterministic work; nothing the toolchain already\nenforces is restated; every reference file is linked directly from SKILL.md rather than only through another\nreference file, every reference link stays inside the plugin directory, and any reference file over roughly 100 lines\nopens with a ## Contents list unless it is a template copied whole into output.writing-effective-instructions.md, workflow-patterns.md) — steps are specific and\nactionable; constraints embed reasoning; error handling is present; human gates sit only at irreversible actions; the\nmost critical item in each list is placed last.allowed-tools-bash-permissions.md, allowed-tools-AskUserQuestion.md,\nsecurity-restrictions.md) — Bash permissions are scoped correctly with separate entries; AskUserQuestion is\nabsent from allowed-tools; no angle brackets or non-standard YAML in frontmatter.dynamic-project-discovery.md, graceful-degradation.md,\noptional-git-repositories.md) — the skill discovers project specifics dynamically rather than hardcoding them, and\ndegrades gracefully when a tool or git is absent, where relevant.agent-dispatch-namespacing.md) — if the skill dispatches agents, every dispatch uses the qualified\ndefining-plugin:agent-name, and the agents actually exist in an installed plugin.success-criteria-and-testing.md) — each use case maps to a triggering and functional test the user can\nrun.Apply the YAGNI discipline throughout: every step, reference file, tool permission, and frontmatter field must earn its\nplace against a real use case. Cut anything added \"for completeness\" or \"for future flexibility.\"
\nSummarize for the user:
\nNote that plugin entities rarely land in one pass: per iterative-plugin-development.md, plan for 3-5 iterations. Ask\nwhether the user wants to iterate on specific steps or considers the skill ready to test.