holocron/plugins/kyberforge/skills/skill-write/SKILL.md

name, description, allowed-tools, metadata

name	description	allowed-tools	metadata
skill-write	Author a new skill following the agentskills.io specification — scaffold the directory structure from annotated templates, fill in SKILL.md and supporting files, then validate the result. 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. 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.	Bash Read Write	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 scripts/new-skill.sh <skill-name> <destination-dir>

Examples:

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

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:

## Gotchas
- <Fact that defies a reasonable assumption>
- <Non-obvious naming discrepancy or hidden constraint>

Default with escape hatch (not a menu):

Use <X> for <task>. For <edge case>, use <Y> instead.

Prescriptive sequence (when order is critical or fragile):

Run exactly:
\`\`\`bash
<command>
\`\`\`
Do not modify flags.

Checklist (multi-step workflows):

- [ ] 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.