--- 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"). 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 ``` **Embedding org-specific policy** — if a skill encodes a rule sourced from an org convention file (e.g. `core/instructions/*.md`), inline that content directly into the skill (SKILL.md or a `references/` file) rather than pointing to the file's path. Plugins must be self-contained and portable — the org file may not exist wherever the plugin is installed, and in this repo such files are meant to be deleted once their content is fully embedded downstream. Tag the inlined content with a `source_keys` entry using the same `references/sources.md` schema as Step 5, noting in the `Research doc:` field that the source is an org convention rather than a plugin research corpus entry, so provenance survives after the source file is gone. **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 - -