---
name: skill-write
description: >
  Use when the user wants to create a new skill from scratch, says "write a skill
  for X", "build a skill that does Y", or "create a SKILL.md for Z", or wants to
  make a workflow repeatable or shareable as a reusable command. Authors a new
  skill following the agentskills.io specification — scaffolds the directory
  structure from annotated templates, fills in SKILL.md and supporting files, then
  validates the result. Performs best when preceded by a grill session and domain
  research. Do not use to update an existing well-formed skill, write evals, or
  author agent definition files.
allowed-tools: Bash Read Write
metadata:
  category: factory
---

## Prerequisites

Run `/grill-me` on the skill's design and research the target domain first.
Share those outputs in this conversation: grill context, research docs, examples, constraints.

**Before touching the filesystem, verify you have:**
- [ ] A clear purpose — what specific task will this skill handle?
- [ ] Trigger scenarios — when should an agent activate it, including indirect cases?
- [ ] Skill name (kebab-case) and destination path

If any are missing, stop and ask the user before proceeding.

**Requires `/skill-audit`** — used in Step 5 for final validation. Both skills ship in the kyberforge plugin and are co-installed. If `/skill-audit` is unavailable, stop and ask the user to install the kyberforge plugin before continuing.

## Step 1 — Scaffold

Run the copy script with the skill name and destination directory:

```bash
bash scripts/new-skill.sh <skill-name> <destination-dir>
```

Examples:
```bash
bash scripts/new-skill.sh my-tool ~/.agents/skills/
bash scripts/new-skill.sh data-analyzer plugins/myplugin/skills/
```

This creates `<destination-dir>/<skill-name>/` with annotated templates ready to fill in.

If the destination is inside a plugin directory (path contains a `plugin.json`), read `references/deployment-modes.md` before adding any file references to SKILL.md.

## Step 2 — Fill in SKILL.md

Open `<destination-dir>/<skill-name>/SKILL.md`. Replace every `FILL IN:` placeholder.

### Frontmatter

**`name`** — already set by the scaffold script. Must exactly match the directory name.

**`description`** — carries the entire triggering burden. Rules:
- Imperative: "Use when..." not "This skill..."
- Specific about capabilities ("parses and validates OpenAPI specs", not "helps with APIs")
- Include indirect triggers: "even if the user doesn't mention X explicitly"
- Add "Do not use when..." only if a near-miss skill exists that could steal activations
- Hard limit: 1024 characters — count before finalizing

**Optional fields** — uncomment and fill in or remove entirely:
- `license` — include when distributing the skill externally
- `compatibility` — include if the skill requires specific tools, runtimes, or network access
- `metadata` — key-value map; use `author`, `version`, `category`
- `allowed-tools` — space-separated pre-approved tools; reduces permission prompts

### Body — include only what the agent lacks

Rename the placeholder section heading to one that fits the skill's structure — `## Step 1`, `## Workflow`, `## Instructions`, etc.

Ask of every sentence: "Would the agent get this wrong without it?" Cut anything that answers "no."

**Include:**
- Non-obvious sequences or ordering constraints — the agent may skip or reorder steps without this
- Domain conventions the agent cannot infer from general knowledge — this is the core value a skill adds
- One default per decision point, plus one escape hatch — never a menu; menus cause the agent to pause or pick arbitrarily
- Gotchas — facts that defy reasonable assumptions; the agent will get these wrong every time without them

**Exclude:**
- Concepts the agent already knows (what JSON is, how HTTP works) — adds tokens without changing behavior
- Exhaustive option lists — pick a default; the agent doesn't benefit from choosing
- Steps the agent handles independently — over-specifying leads agents to follow unproductive paths
- Restatements of the description — it's already in context; repeating it wastes the token budget

### Patterns

**Gotchas** — highest value; place near the top:
```markdown
## Gotchas
- <Fact that defies a reasonable assumption>
- <Non-obvious naming discrepancy or hidden constraint>
```

**Default with escape hatch** (not a menu):
```markdown
Use <X> for <task>. For <edge case>, use <Y> instead.
```

**Prescriptive sequence** (when order is critical or fragile):
```markdown
Run exactly:
\`\`\`bash
<command>
\`\`\`
Do not modify flags.
```

**Checklist** (multi-step workflows):
```markdown
- [ ] Step 1: ...
- [ ] Step 2: ...
```

**Conditional reference** (progressive disclosure — load only when needed):
```
If <condition>, read `references/<file>.md`.
```

### Size budget

Keep `SKILL.md` under 500 lines. When approaching the limit:
- Move reference material to `references/<topic>.md` and load it conditionally
- Bundle repeated executable logic into `scripts/` rather than reinventing each run

## Step 3 — Add scripts (if needed)

Place executable scripts in `scripts/`. Rules for agentic scripts:

- **No interactive prompts** — agents run non-interactive; blocking on TTY input hangs indefinitely. Accept all input via flags, env vars, or stdin.
- **Expose `--help`** — concise usage output; keep it short (it enters the agent's context)
- **Structured output** — data (JSON, CSV) to stdout; diagnostics and progress to stderr
- **Idempotent** — "create if not exists"; agents may retry on failure
- **Meaningful exit codes** — `0` success, non-zero failure; document in `--help`
- **Dry-run support** — add `--dry-run` for destructive operations

If the skill needs scripts with external package dependencies or language-specific tooling (Python, TypeScript, Ruby, Go), read `references/scripts.md` for package runner patterns and inline dependency formats.

If no scripts are needed, delete `scripts/README.md` and the `scripts/` directory.

## Step 4 — Add references, assets, and tests (if needed)

**`references/`** — additional documentation loaded on demand. One topic per file.
Reference conditionally from SKILL.md: `If <condition>, read references/<file>.md`.

**`assets/`** — static resources: templates, schemas, lookup tables.
Reference by relative path from SKILL.md.

**`tests/`** — test files for scripts in `scripts/`. Use when scripts are complex
enough to break silently. Test infrastructure (`.bats`, `*_test.*`) belongs here,
not in `scripts/`. See `tests/README.md` for setup instructions.

If not needed, delete the placeholder READMEs and their directories.

## Step 5 — Validate

Run `/skill-audit` on `<destination-dir>/<skill-name>`.

All FAIL findings must be resolved before the skill is considered done.