/ha-skill-creator

name: ha-skill-creator
description: "Create, edit, improve, or audit Hope Agent skills. Use when the user wants to: (1) create a new skill from scratch, (2) edit or improve an existing skill, (3) review or clean up a SKILL.md file, (4) run evaluations to test skill effectiveness, (5) optimize skill descriptions for better trigger accuracy. Trigger phrases: 'create a skill', 'make a skill', 'improve this skill', 'review skill', 'audit skill'."
always: true

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)

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