--- source_keys: - agentskills-home - agentskills-spec - agentskills-best-practices - agentskills-quickstart - agentskills-using-scripts --- # Creating a new skill Return to `SKILL.md` Step 4 once Step 6 below is done — validation, versioning and commit verification are shared with the improve flow and are not repeated here. ## 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? - [ ] Skill name (kebab-case) and destination path If any are missing, stop and ask the user before proceeding. **Requires `/factory-audit`** — used in `SKILL.md` Step 4 for final validation. Both skills ship in the kyberforge plugin and are co-installed. If `/factory-audit` is unavailable, stop and ask the user to install the kyberforge plugin before continuing. ## Package-intent gate Judge whether the destination is meant to be inside an APM package before running the scaffold script — the script cannot tell "no package here" apart from "package not scaffolded yet": - Package intent but no `type:`-bearing `apm.yml` found at or above the destination (e.g. "add to my apm package", or a sibling `.apm/`/`apm.yml` exists nearby) → **stop**, tell the user to run `/apm-workflow configure` (`apm plugin init`, from inside the package directory) first, then retry. Do not fall through to standalone mode. - Otherwise (a `~/`-rooted destination, or no package context implied) → continue to Step 1. ## Step 1 — Scaffold Run the copy script with the skill name and a path inside or at the target: ```bash bash scripts/new-skill.sh ``` The script walks up from `` for a package boundary: an ancestor `apm.yml` with a top-level `type:` field (`instructions`/`skill`/`hybrid`/`prompts`) means **package mode** — scaffolds into `/.apm/skills//`, not under `` (a subdirectory of the package works fine as ``). A `type:`-less `apm.yml` is a marketplace-only manifest, skipped. Hitting `.git` or the filesystem root first means **standalone mode** — scaffolds directly into `//`. Examples: ```bash # Package mode — packages/my-pkg/apm.yml already has `type: skill` bash scripts/new-skill.sh my-tool packages/my-pkg/ # Standalone mode — no apm.yml/.git above ~/.agents/skills/ bash scripts/new-skill.sh my-tool ~/.agents/skills/ ``` The script prints which mode it used and where the skill landed — read its output. In package mode, read `references/deployment-modes.md` before adding any file references to SKILL.md. ## Step 2 — Update `apm.yml` includes (package mode only) Skip in standalone mode. In package mode, check the resolved package's `apm.yml`: if `includes:` is an explicit list (not `auto`), append `.apm/skills//` to it if not already present, preserving YAML formatting. If `includes: auto` or the field is absent, do nothing — `auto` already covers the new skill. Use Read/Edit directly on `apm.yml`; this is not part of `scripts/new-skill.sh`. ## Step 3 — Fill in SKILL.md Open the new skill's `SKILL.md` (the path Step 1 printed) and replace every `FILL IN:` placeholder. The scaffold template carries the body skeleton and the two frontmatter fields that cannot be left as placeholders — `name`, substituted by the script, and `metadata.version`, seeded live at `"0.1.0"` — so fill the template in rather than restructuring it. **`name`** — already set by the scaffold script. Must exactly match the directory name. Format: 1–64 characters, lowercase letters, numbers and hyphens only; no leading, trailing or consecutive hyphens (`--`). **`description`** — carries the entire triggering burden and is preloaded every session. Write it against `references/contract.md`, which holds the three-part shape, the banned content, the boundary-clause form and the length tiers. A hand-invoked skill (`SKILL.md` Step 2) takes one plain sentence and `disable-model-invocation: true` instead. **`metadata.version`** — required on every skill (ADR-0022), not a per-skill or per-plugin choice, and enforced by the `skill-size-check` pre-commit hook. The scaffold seeds a new skill at `"0.1.0"`; leave that value alone here and let `SKILL.md` Step 4 bump it. (`"1.0.0"` is the seed for a pre-existing skill retrofitted into the rule, and never applies to a skill created here.) **Optional frontmatter** — 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` — the rest of the map, all of it optional: `author` and `category`, plus `source_keys` now (Step 6) if research sources are in context - `allowed-tools` — space-separated pre-approved tools; reduces permission prompts (experimental — support varies by client) - `disable-model-invocation` — hand-invoked skills only **`metadata.source_keys`** — if research sources are in context, list the relevant slugs as you write the body; do not defer this to Step 6. Agents that fill in `source_keys` late tend to omit it entirely. Example: ```yaml metadata: source_keys: - my-source-slug - another-slug ``` **Body** — write the decision procedure only, following the body rules and patterns in `references/contract.md`. Rename the placeholder section headings to ones that fit the skill's structure. ## Step 4 — Add scripts (if needed) Place executable scripts in `scripts/`. Critical rule: **no interactive prompts** — agents run non-interactive, and blocking on TTY input hangs indefinitely. Accept all input via flags, env vars, or stdin. If adding a script, read `references/scripts.md` first — it covers the full contract: structured output, pinned versions, self-contained deps, idempotency, exit codes, dry-run, error messages, and output size limits. If no scripts are needed, delete `scripts/README.md` and the `scripts/` directory. ## Step 5 — Add references, assets, and tests (if needed) **`references/`** — additional documentation loaded on demand. One topic per file, named in kebab-case after the topic. Reference conditionally from SKILL.md with the literal form ``If , read `references/.md` ``. **Two hops from `SKILL.md`, never three.** A flow file may route on to a shared contract or sub-topic file — that is the shipped pattern here (`SKILL.md` → `references/create.md` → this file's own pointers to `contract.md`, `scripts.md` and `deployment-modes.md`). What does not work is a third hop: a file reachable only through two intermediates is rarely loaded at the moment it is needed. Every hop past the first also needs the same literal conditional form, so the agent knows when to take it. **`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 6 — Populate or delete `references/sources.md` If a research `sources.md` is present in the conversation context: 1. Read it and filter to entries with `` `extracted` `` status only. 2. For each entry, determine which skill files it contributed to (SKILL.md and any files in `references/` that drew from it). Update `Contributing files` accordingly — list skill files, not research topic files. 3. Write the updated content to `references/sources.md`. Every entry carries exactly one `- **Research doc:** ` line. `` is the relative path from the repo root to the **Research registry** — the plugin-level research `sources.md` whose `## H2` headings are the source slugs (e.g. `plugins/myplugin/docs/research/docs//sources.md`) — never a topic document, and never a list: no brace expansion, no comma- or semicolon-separated paths, no second `Research doc:` line. A pointer to the topic document that digested the source goes in an annotation after the path, e.g. ` (digest: )`, where it is not checked. `/factory-audit` fails a slug missing from the registry it names. If the entry has no Research registry — an org convention, an ADR, a reproduction backed by committed fixtures or tests named in `Basis:` — write `- **Research doc:** none` and name what it was drawn from with one `- **Basis:** ` line per path. Each Basis path is checked to exist; annotate one that has since been deleted `(removed in )` and the check is skipped. `none` with no Basis is a FAIL. 4. Add `source_keys` to the frontmatter of `SKILL.md` (under `metadata`) listing the slugs of sources that informed it. 5. For each file in `references/` that was informed by research sources, add `source_keys` frontmatter (same format as research topic files) listing the relevant slugs. If no research `sources.md` is in context, delete `references/sources.md`. Then return to `SKILL.md` Step 4.