skill-builder

## 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 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