/skill-builder

name: skill-builder
description: >
  Builds a new Claude Code skill from scratch through a relentless, evidence-based interview that walks the skill's
  design tree decision-by-decision — entity fit, use cases, name, description, workflow steps, tools, and
  progressive-disclosure layout — then reviews the finished skill against the plugin-building guidance and applies every
  fix it finds. Use when creating, authoring, scaffolding, designing, or drafting a new skill or slash command. Does not
  build an agent or subagent — use agent-builder. Does not serve, vendor, or refresh the authoring guidance itself — use
  guidance.
allowed-tools:
  Read, Write, Edit, Glob, Grep, Bash(find *), Bash(mkdir *),
  Bash(bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh")

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](../../references/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