Files

Defame1297 311e7cd22c fix(kyberforge): reconcile the authoring rules the ADR-0020 trim left disagreeing

Six defects, each one a place where two files that an author reads in the same
sitting told them different things — or where the trim dropped a rule and nothing
noticed because no gate covers prose.

**"Use proactively" contradicted itself across the pair.** All three agent
templates said to add it where the runtime should delegate unprompted, while
`agent-audit`'s `KyberforgeCopilot.ProactivePhrase` rule grades it a hard FAIL in
any `*.agent.md` — which is the Copilot half of every project/user pair *and* the
vendor-neutral plugin-scope file, since that compiles to a real Copilot agent
downstream. Following the template produced a file the repo's own gate rejects.
The phrase is now permitted in exactly one place, the Claude Code `.md`, and
`references/contract.md` carries the per-file table plus the consequence authors
ask about next: a pair whose CC half has it and whose Copilot half does not is
correct, because `agent-audit` checks that both halves describe the same job, not
that they match word for word.

**The output-schema rule contradicted itself inside one file.** `contract.md`
said any content only one branch reaches moves to `references/`, and then offered
an "Output format template" body pattern with no qualification. Stated once now,
so it is not re-litigated: an output schema stays in the body only when every flow
produces it and it is roughly 50 words or less. No third option.

**Gotchas tiers disagreed with the script.** `validate.sh` emits the entry count
through `suggest()` and exits 0, while `skill-author` and `skill-audit` both
called more than five entries a FAIL. Whether a given gotcha earns its place is
judgment, so the prose moves to the script's tier rather than the reverse. The
paraphrase rule stays a FAIL and is explicitly marked as the auditor's call — no
script detects it.

**The dispatch exemplar was cited at the wrong number.** `apm-workflow`'s body is
421 words; 554 is its whole-file count. Both `contract.md` and `body-discipline.md`
cited 554 while describing a body budget, so an author calibrating against the
exemplar overshot by ~30% — the exact whole-file/body-only conflation those two
sections exist to warn against, reproduced inside the warning.

**"Error handling" came back as a required body element.** It was one of four and
is the one that gets dropped, and dropping it is not neutral: an agent handed
malformed input with no instruction invents a recovery, and a subagent's invented
recovery is invisible to its caller until the output is wrong. Restored in
`agent-audit`'s rubric as a SUGGESTION, in `agent-author`'s contract and both
scope checklists as a required element, and as an `## Errors` section in all three
templates.

**`skill-author` Step 4 gains the one check the audit misses.** An empty body
reports `PASS SKILL.md body word count 0` — a word gate cannot tell "concise"
from "absent". Step 4 now hand-checks for a non-empty section, and its commit
verification is conditioned on actually being inside a git worktree, which a skill
under `~/.claude/skills/` is not.

Also here: absolute repo paths removed from `skill-author`'s SKILL.md and
contract.md in favour of naming the skill (`zoom-out`'s description is quoted
inline instead of pointed at), the boundary-target universe documented to match
the resolver, a two-hops-from-SKILL.md limit on reference chains, and
`new-agent.sh`'s next-steps output naming the description budget and the
deliberate absence of an agent body gate.

Refs: ADR-0020

2026-08-16 16:40:51 +00:00

8.2 KiB

Raw Blame History

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 /skill-audit — used in SKILL.md Step 4 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.

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 scripts/new-skill.sh <skill-name> <path>

The script walks up from <path> for a package boundary: an ancestor apm.yml with a top-level type: field (instructions/skill/hybrid/prompts) means package mode — scaffolds into <package-root>/.apm/skills/<skill-name>/, not under <path> (a subdirectory of the package works fine as <path>). A type:-less apm.yml is a marketplace-only manifest, skipped. Hitting .git or the filesystem root first means standalone mode — scaffolds directly into <path>/<skill-name>/.

Examples:

# 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/<skill-name>/ 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 already carries the compliant frontmatter and body skeleton — fill it 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.

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 — key-value map; use author, version, category; add 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:

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 <condition>, read `references/<file>.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:

Read it and filter to entries with `extracted` status only.
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.
Write the updated content to references/sources.md. For each entry, include - **Research doc:** <path> where <path> is the relative path from the repo root to the plugin-level research sources file this entry was drawn from (e.g. plugins/myplugin/docs/research/docs/<topic>/sources.md). This field is required on every entry — it makes the provenance chain explicit and is validated by /skill-audit.
Add source_keys to the frontmatter of SKILL.md (under metadata) listing the slugs of sources that informed it.
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.

8.2 KiB Raw Blame History Unescape Escape