ha-skill-creator

# Skill Creator

Tool for creating new skills and iteratively improving existing ones.

## Skill System Overview

Hope Agent skills are modular, self-contained packages that extend the AI assistant's capabilities with domain knowledge, workflows, and tools. Skills turn a general-purpose AI into a domain-specific expert.

### Skill Loading (Three-Tier Progressive Disclosure)

1. **Catalog metadata** (name + description, plus optional Claude-style when_to_use) — injected only when the skill is eligible and visible (~100 words)
2. **SKILL.md body** — loaded when the skill triggers (ideal <500 lines)
3. **Bundled resources** — loaded on demand (scripts can be executed directly, no need to read into context)

### Body Organization — Three Common Patterns

Pick the pattern that matches the skill's shape. Most skills fit cleanly
into one; some mix patterns (e.g. start task-based, add a workflow for
the one complex operation). All three keep the body short by pushing
depth into `references/`.

**1. Workflow-based** — sequential process with ordered steps.
Best for builds, deployments, delivery pipelines, investigations.

```
SKILL.md
├── ## Overview
├── ## Step 1 — <setup>
├── ## Step 2 — <main action>
├── ## Step 3 — <verify / publish>
└── ## Troubleshooting   (refers to references/*.md per step)
```

**2. Task-based** — capability menu, operations are independent.
Best for analysis tools and skills offering several unrelated features.

```
SKILL.md
├── ## Overview
├── ## Quick Start
├── ## Task: <feature A>
├── ## Task: <feature B>
└── ## Task: <feature C>
```

**3. Reference-based** — specification / rules / standards.
Best for style guides, API schemas, brand rules.

```
SKILL.md
├── ## Overview
├── ## Core Rules
└── (detailed spec in references/<area>.md, loaded on demand)
```

### Skill Directory Structure

```
skill-name/
├── SKILL.md          (required: frontmatter + Markdown instructions)
├── scripts/          (optional: executable scripts, Python/Bash etc.)
├── references/       (optional: reference docs loaded on demand)
└── assets/           (optional: templates, icons, output materials)
```

### Skill Sources (lowest → highest precedence)

1. **Bundled** — shipped with Hope Agent, `skills/` directory
2. **Extra directories** — user-imported, `config.json` `extraSkillsDirs`
3. **Managed** — `~/.hope-agent/skills/`
4. **Project** — `.hope-agent/skills/` (relative to cwd, highest precedence)

---

## SKILL.md Format Specification

### Frontmatter (YAML)

```yaml
---
# ── Required ──
name: my-skill                          # Skill identifier (lowercase + hyphens)
description: "Short summary of what the skill does and when to use it."
when_to_use: "Optional Claude-style trigger hint — duplicate the key trigger words in description for OpenAI/AgentSkills portability"

# ── Optional: Identity ──
aliases: [alt-name-1, alt-name-2]       # Extra slash-command names for the same skill

# ── Optional: Prerequisites ──
requires:
  bins: [git, gh]                       # All must exist in PATH (AND)
  anyBins: [rg, grep]                   # At least one must exist (OR)
  env: [GITHUB_TOKEN]                   # Required environment variables
  os: [darwin, linux]                   # Supported operating systems
  config: [webSearch.provider]          # Config paths that must be truthy
always: false                           # true = skip prerequisite checks; not locked/unclosable
primaryEnv: MY_API_KEY                  # Primary env var (can be satisfied by apiKey)

# ── Optional: Invocation Control ──
user-invocable: true                    # Register as /command slash command
disable-model-invocation: false         # true = hide from model prompt directory
skillKey: custom-key                    # Custom config lookup key

# ── Optional: Command Dispatch ──
command-dispatch: tool                  # "tool" or "prompt"
command-tool: exec                      # Tool to bind when dispatch=tool
command-arg-mode: raw                   # Argument passing mode
argument-hint: "<query>"                # Claude canonical UI placeholder hint (aliases: argumentHint, command-arg-placeholder)
command-arg-options: [on, off]          # Fixed argument options
command-prompt-template: "..."          # Template with $ARGUMENTS expansion

# ── Optional: Execution Mode ──
context: inline                         # "fork" = sub-agent, "inline" = main conversation (see guidance below)
allowed-tools: [read, grep, glob]       # Tool whitelist for fork / skill-tool execution; slash inline currently does not enforce it
agent: code-reviewer                    # Sub-agent type to use when context=fork (optional)
effort: medium                          # Reasoning effort for forked sub-agent (low|medium|high|xhigh|none)

# ── Optional: Dependency Installation ──
install:
  - kind: brew
    formula: gh
    bins: [gh]
    label: "Install GitHub CLI (brew)"
    os: [darwin]
  - kind: node
    package: "@anthropic-ai/sdk"
    bins: [anthropic]
  - kind: go
    module: github.com/user/tool@latest
  - kind: uv
    package: my-python-tool
---
```

### Execution Mode — Fork vs Inline

`context:` decides where the skill runs. The choice matters: a wrong pick
either pollutes the main conversation with noisy tool output or hides
intermediate state the user needs to steer.

| Use `fork` (sub-agent) when | Use `inline` (main conversation) when |
|---|---|
| The skill runs many `exec` or `read` calls whose output is a one-time consumable | The user will react to intermediate output before the skill finishes |
| Work is self-contained — you can hand the caller a summary | You need `ask_user_question` inside the flow |
| Typical: builds, deployments, packaging, data pipelines | Typical: code review, interactive refactors, iterative writing |
| You explicitly want noise-isolated tool results | Tool calls are few and lightweight (1–3) |

Under the hood `fork` spawns a sub-agent with the skill's `allowed-tools`,
runs to completion, and injects *