--- name: skill-author description: > Use when the user wants to create a new skill from scratch ("write a skill for X", "build a skill that does Y", "create a SKILL.md for Z") or improve an existing one ("improve this skill", "fix based on feedback", "apply these audit findings", "update based on grill output"). Handles both the full create flow (scaffold → fill → validate) and the improve flow (signals → root cause → edit → audit). Also use when the user provides inline feedback about a skill's behavior and wants it applied, or when a grill session, eval run, or audit has produced findings the user wants acted on — even if they don't say "improve" explicitly. Do not use for read-only review — use /skill-audit instead. Do not use to author agent definition files. allowed-tools: Bash Read Write Edit metadata: category: factory source_keys: - agentskills-home - agentskills-spec - agentskills-best-practices - agentskills-optimizing-descriptions - agentskills-evaluating-skills - agentskills-using-scripts - agentskills-quickstart --- ## Gotchas - Patching per symptom is the default failure mode. Three eval failures may all trace to one missing instruction — always identify the root cause before editing. - Do not create new scripts unless a signal explicitly calls for it. Writing scripts from scratch requires transcript analysis that is out of scope here; flag the opportunity as a suggestion instead. ## Route Determine which flow to follow before touching the filesystem: - **No skill directory at the target path** → follow **Creating a new skill** - **Directory exists + at least one improvement signal present** → follow **Improving an existing skill** - **Directory exists + no signals present** → ask: "No improvement signals found. Did you mean to create a new skill, or do you have feedback to apply?" Signals include: grill session output, `/skill-audit` findings (PASS/FAIL punch list), inline user feedback, session context describing what went wrong. ## Creating a new skill ### 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. Design for one coherent user intent — skills too narrow force multiple loads per task; too broad are hard to activate precisely. **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 6 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 ``` Examples: ```bash bash scripts/new-skill.sh my-tool ~/.agents/skills/ bash scripts/new-skill.sh data-analyzer plugins/myplugin/skills/ ``` This creates `//` 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 `//SKILL.md`. Replace every `FILL IN:` placeholder. **Frontmatter** **`name`** — already set by the scaffold script. Must exactly match the directory name. Format: 1–64 characters, lowercase letters/numbers/hyphens only, no leading, trailing, or consecutive hyphens (`--`). **`description`** — carries the entire triggering burden. Rules: - Imperative: "Use when..." not "This skill..." - Focus on user intent, not implementation — describe what the user is trying to achieve, not the skill's internal mechanics - 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 (max 500 characters) - `metadata` — key-value map; use `author`, `version`, `category`; add `source_keys` now (see below) if research sources are in context - `allowed-tools` — space-separated pre-approved tools; reduces permission prompts (experimental — support varies by client) **`metadata.source_keys`** — if research sources are in context, list the relevant slugs here as you write the body; don't defer this to Step 5. Agents that fill in source_keys late tend to omit it entirely. Example: ```yaml metadata: source_keys: - my-source-slug - another-slug ``` **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 - -