holocron/plugins/kyberforge/skills/skill-author/SKILL.md at 36ba7a18f8cdccc218521eca16c28a476401cffa

Files

Defame1297 4a5c3c0cff feat(kyberforge): enforce the ADR-0020 context contract for skills and agents

Skill name+description pairs are preloaded into every session, costing
~6,200 tokens across 39 skills before any skill is invoked. The authoring
rules mandated that growth: skill-author:104 and description-quality.md:21
both required padding, while skill-author:102 (the deflating rule) had no
FAIL condition behind it.

Gates (blocking, no baseline file):
- description 250 chars SUGGESTION / 400 FAIL, measured on the folded
  YAML value
- body-only 600 words SUGGESTION / 900 FAIL, independent of the unchanged
  whole-file 2770-word / 500-line spec backstop
- every boundary-clause routing target must resolve to a real skill or
  agent; catches skill-improve, neuledge-context and gitea-labels
- agents take the description gates but deliberately no body gate; a test
  pins that absence

Vale: DescriptionOpener widened to ^This\b, new CompositionNote rule
banning architecture notes from descriptions. 10 hits, 0 false positives.

Kyberforge's own four skills retrofitted: descriptions 3,364 -> 938 chars
(-72%), bodies 8,306 -> 2,487 words (-70%), all via the apm-workflow
dispatch pattern. Fixes the skill-improve dangling route and the
agent-author misroute to manual review.

Also fixes a pre-existing false positive where any line-initial 'read '
was flagged as interactive input, which had already caused two scripts to
be rewritten around it.

Refs: ADR-0020

2026-08-14 21:13:13 +00:00

4.3 KiB

Raw Blame History

name, description, allowed-tools, metadata

name

description

allowed-tools

metadata

skill-author

Use when the user wants to create a new skill from scratch, or apply audit findings, grill output, eval results, or inline feedback to an existing one. Not read-only review -> `skill-audit`. Not agent files -> `agent-author`.

Bash Read Write Edit

Gotchas

A skill's name and description are preloaded into every agent's context every session, invoked or not; the body loads only on invocation. The description is the scarce budget.
The word gates are two different measurements, not one rule with two tiers. The 2,770-word / 500-line spec backstop counts the whole file including frontmatter; Step 3's gate counts the body alone. A file can sit well inside one and fail the other, so never unify them.
Never spawn a subagent to audit or recheck your own work here. Run /skill-audit inline, in the same context as the edits. Clean-context recheck belongs to /forge's outer loop, and a self-spawned subagent can have its worktree torn down by concurrent cleanup, destroying an uncommitted draft.
Do not create new scripts unless a signal explicitly calls for it. Writing one from scratch requires transcript analysis that is out of scope here — flag the opportunity as a suggestion instead.

Step 1 — Dispatch

Condition	Flow	Reference
No skill directory at the target path	Create	`references/create.md`
Directory exists, at least one improvement signal present	Improve	`references/improve.md`
Directory exists, no signals	Stop and ask	—

Signals: grill output, /skill-audit findings, inline feedback, eval results, session context describing what went wrong. With none, ask: "No improvement signals found. Did you mean to create a new skill, or do you have feedback to apply?"

Read only the reference matching the resolved flow — each is self-contained. Capture git log --oneline -1 before touching the filesystem; Step 4 needs it.

Step 2 — Invocation axis

Decide before writing any description: model-invoked or hand-invoked?

Hand-invoked — the user types /name and no agent should route to it. Set disable-model-invocation: true and write one plain human-facing sentence: no trigger list, no boundary clause. Worked example: plugins/bin/.apm/skills/zoom-out/SKILL.md. Skip Step 3's description rules.
Model-invoked — the default.

Step 3 — Contract

Before writing or editing a description, or restructuring a body, read references/contract.md — the banned-content list, boundary form, include/exclude rubric and body patterns.

Gates /skill-audit enforces in both flows:

Description — a trigger clause, at most one capability clause, and a boundary clause shaped Not <thing> -> <skill-name> whose target resolves to a real skill or agent. 250 characters SUGGESTION, 400 FAIL, value only.
Body — decision procedure only: ordered steps, branches, gates, and which reference to load when. 600 words SUGGESTION, 900 FAIL, body only. At two or more mutually exclusive flows a dispatch table is mandatory and each flow gets its own self-contained references/ file.
Gotchas — at most five, each contradicting a reasonable default. A Gotcha paraphrasing a step below it is a FAIL.

Step 4 — Validate and close

Run /skill-audit on the resolved skill directory. It checks name-to-directory match, description presence, leftover FILL IN: placeholders, both size budgets, boundary-target resolution and script hygiene — do not hand-check those first. Resolve every FAIL before reporting done.

With metadata.version present, bump the minor version on create (new skills start at 0.1.0) and the patch version on improve.

Commit verification. Once the audit is clean, run git add and git commit — do not stop at staging. Re-run git log --oneline -1 and confirm the hash changed from the one captured at Step 1. A non-empty git diff --stat is not proof: staged-but-uncommitted work is part of no commit and is silently lost if the tree is cleaned up first. Report done only once the hash has changed.

4.3 KiB Raw Blame History