docs: trim skill READMEs and ADR/changelog narration
Two related simplification-audit findings, bundled because they edit some of the same skill-audit files and splitting would fragment single-file diffs. Finding 10: delete 48 per-skill/reference README.md files (they restated SKILL.md in narrative form and no agent ever loads them) plus 2 scaffold templates. Drop the README criterion from skill-audit's file-structure.md and finding-criteria.md, and the README-generation step from skill-author's new-skill.sh; update new-skill.bats to match. Plugin-root READMEs are kept intentionally, out of scope. Finding 12: strip historical ADR-0020/ADR-0023 citations and changelog-style narration from model-facing skill content across kyberforge and git plugin skills. Delete skill-author's one-time retrofit.md migration guide and its references. Some ADR-0023 tags were not narration but check-rtk-prefix's required opt-out marker for intentionally-bare git commands -- those were restored, not stripped. Mirror re-synced and full pre-commit/pre-push suite verified green. Refs: SIMPLIFICATION-AUDIT.md findings 10, 12 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
This commit is contained in:
@@ -1,79 +0,0 @@
|
||||
# agent-audit
|
||||
|
||||
Audits an agent definition for correctness and quality against the Claude Code and Copilot agent
|
||||
references and the house context-budget contract (ADR-0020) — a single vendor-neutral file at
|
||||
plugin/APM scope, or a Claude Code and Copilot file pair at project/user scope.
|
||||
|
||||
## What it does
|
||||
|
||||
1. Runs `scripts/validate.sh` and `scripts/validate-provenance.sh` for structural and provenance
|
||||
checks, plus `scripts/vale-wrap.sh` — a Vale prefilter that deterministically flags
|
||||
non-imperative description openers, composition and architecture notes, vague wording, padding
|
||||
phrases, "There is/are" sentence openers, and CC-specific "Use proactively" phrasing in a
|
||||
Copilot or vendor-neutral description
|
||||
2. Reads the agent file, and its counterpart when one exists, then loads the contract for its scope
|
||||
3. Applies qualitative checks across description, body, delegation and comment discipline, loading
|
||||
one rubric from `references/` per group
|
||||
4. Outputs a compact findings report — findings only, grouped by dimension, each with Why and Fix —
|
||||
and a result block with handoff to `agent-author`
|
||||
|
||||
Two things follow from ADR-0020 and are easy to get backwards. Agents take the **same** description
|
||||
gates a skill takes — 250 characters SUGGESTION, 400 FAIL, since a `name` + `description` is
|
||||
preloaded into every session either way — and **no body word gate at all**, because an agent body
|
||||
becomes the system prompt of a fresh context rather than competing with the caller's live
|
||||
conversation. Body length is judged through the delegation check instead: an agent body that
|
||||
restates a procedure owned by a skill it can invoke is a FAIL, because a plugin-scope agent has no
|
||||
sibling `references/` directory to disclose to and can only delegate.
|
||||
|
||||
At **plugin/APM scope** the audit accepts the single `.apm/agents/<name>.agent.md` file — there is
|
||||
no counterpart, and pair consistency does not apply. `validate.sh` hard-`FAIL`s any frontmatter
|
||||
field outside the vendor-neutral allowlist, since `apm compile` copies frontmatter verbatim to both
|
||||
harnesses and an unsafe field cannot be silently dropped for just one of them. The allowlist lives
|
||||
in the `apm-agent-allowlist` section of `references/field-inventory.md`, is read from there as data
|
||||
by the script, and is deliberately not restated anywhere else in this skill (ADR-0009).
|
||||
|
||||
At **project/user scope** the audit accepts either file in a CC `.md` / Copilot `.agent.md` pair,
|
||||
derives the counterpart automatically, and validates both, including the field-leakage checks in
|
||||
each direction.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/agent-audit
|
||||
```
|
||||
|
||||
Pass the path to either agent file as the argument.
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `SKILL.md` | Skill instructions for agents |
|
||||
| `assets/vale/.vale.ini` | Vale config: scopes `Kyberforge` to `**/agents/*.md`, `Kyberforge`+`KyberforgeCopilot` to `**/*.agent.md` |
|
||||
| `assets/vale/styles/Kyberforge/CompositionNote.yml` | Flags composition and architecture notes in a description ("cross-cutting", "entry point", "composes", "rather than duplicating") that belong in README.md |
|
||||
| `assets/vale/styles/Kyberforge/DescriptionOpener.yml` | Flags descriptions opening with "This..." instead of an imperative "Use when..." |
|
||||
| `assets/vale/styles/Kyberforge/PaddingPhrase.yml` | Flags generic "see references/ for info" pointers instead of specific file references |
|
||||
| `assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml` | Flags sentences opening with "There is/are" instead of naming the subject directly |
|
||||
| `assets/vale/styles/Kyberforge/VagueWording.yml` | Flags vague capability wording ("helps with", "utilize", "assists with", "used for") in descriptions |
|
||||
| `assets/vale/styles/KyberforgeCopilot/ProactivePhrase.yml` | Flags CC-specific "Use proactively" phrasing with no effect in Copilot descriptions |
|
||||
| `references/README.md` | Directory documentation for references/ |
|
||||
| `references/finding-criteria.md` | Every dimension's FAIL and SUGGESTION criteria — the one Step 3 file read on every run; it decides which rubrics below are worth loading |
|
||||
| `references/description-quality.md` | Rubric for the description dimension — why the description is the expensive part, the hand-invoked contract, the three-part shape, indirect triggers, and near-miss exclusions |
|
||||
| `references/body-and-delegation.md` | Rubric for the body, delegation and comment-discipline dimensions — the core test, the delegation FAIL, why agents take no body word gate, and what an agent body is for |
|
||||
| `references/scope-plugin-apm.md` | Scope contract for a single vendor-neutral APM agent file — allowlist, dimension routing, and the dimensions that do not apply |
|
||||
| `references/scope-project-user.md` | Scope contract for a CC / Copilot pair — counterpart derivation, provider field rules, pair consistency |
|
||||
| `references/validation-scripts.md` | Loaded only when a Step 1 script fails or cannot run — scope-detection walk-up, manual fallback checks, known script failures |
|
||||
| `references/field-inventory.md` | Authoritative field lists read as data by `validate.sh`: valid CC and Copilot agent fields, and the vendor-neutral plugin/APM-scope allowlist |
|
||||
| `references/sources.md` | Research provenance for skill content |
|
||||
| `scripts/README.md` | Directory documentation for scripts/ |
|
||||
| `scripts/validate.sh` | Structural validator — required fields, name format, placeholder detection, the ADR-0020 description budget, and the field rules for the detected scope |
|
||||
| `scripts/validate-provenance.sh` | Provenance chain validation against `sources.md` at the package root (plugin/APM scope only) |
|
||||
| `scripts/vale-wrap.sh` | Drop-in `vale` wrapper that works around a frontmatter-description NLP scope limitation |
|
||||
| `tests/README.md` | (source-only) Bats test dependency and run instructions |
|
||||
| `tests/validate.bats` | (source-only) Bats tests for validate.sh |
|
||||
| `tests/validate-provenance.bats` | (source-only) Bats tests for validate-provenance.sh |
|
||||
|
||||
Rows marked **(source-only)** exist in the authoring source (`.apm/skills/agent-audit/`) but are
|
||||
not present in an installed plugin: `scripts/sync-plugin-content.sh` strips
|
||||
`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
|
||||
plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install.
|
||||
@@ -7,7 +7,7 @@ description: >
|
||||
directory -> skill-audit.
|
||||
allowed-tools: Bash Read
|
||||
metadata:
|
||||
version: "1.0.1"
|
||||
version: "1.0.2"
|
||||
category: factory
|
||||
source_keys:
|
||||
- context7-websites-code-claude
|
||||
@@ -34,7 +34,7 @@ bash scripts/validate-provenance.sh <agent-file>
|
||||
bash scripts/vale-wrap.sh <agent-file> [<counterpart-file>]
|
||||
```
|
||||
|
||||
`validate.sh` takes either half of a project/user-scope pair or the single plugin/APM-scope file, detects the provider from the extension and the scope by walking up, then checks required fields, kebab-case `name`, `FILL IN:` placeholders, template HTML comments left in frontmatter, the ADR-0020 description budget (250 chars SUGGESTION, 400 FAIL, measured on the folded YAML value) and the fields that scope permits. Its findings become the `### Structure` dimension — its FAILs and its SUGGESTIONs both — except the ones the Step 2 scope contract re-routes.
|
||||
`validate.sh` takes either half of a project/user-scope pair or the single plugin/APM-scope file, detects the provider from the extension and the scope by walking up, then checks required fields, kebab-case `name`, `FILL IN:` placeholders, template HTML comments left in frontmatter, the description budget (250 chars SUGGESTION, 400 FAIL, measured on the folded YAML value) and the fields that scope permits. Its findings become the `### Structure` dimension — its FAILs and its SUGGESTIONs both — except the ones the Step 2 scope contract re-routes.
|
||||
|
||||
If a validation script fails or cannot run — Bash denied, `python3` or `vale` absent, `references/field-inventory.md` missing — read `references/validation-scripts.md`; what these scripts measure is not reproducible by reading.
|
||||
|
||||
|
||||
@@ -1,20 +0,0 @@
|
||||
---
|
||||
source_keys: []
|
||||
---
|
||||
|
||||
# references/
|
||||
|
||||
Additional documentation agents load on demand.
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `finding-criteria.md` | Every dimension's FAIL and SUGGESTION criteria — the one Step 3 file read on every run; it decides which rubrics below are worth loading. |
|
||||
| `description-quality.md` | Rubric for the description dimension — why the description is the expensive part, the hand-invoked contract, the three-part shape, indirect triggers, and near-miss exclusions. |
|
||||
| `body-and-delegation.md` | Rubric for the body, delegation and comment-discipline dimensions — the core test, the delegation FAIL, why agents take no body word gate, and what an agent body is for. |
|
||||
| `scope-plugin-apm.md` | Contract for a single vendor-neutral `.apm/agents/<name>.agent.md` file — allowlist, dimension routing, and the dimensions that do not apply. |
|
||||
| `scope-project-user.md` | Contract for a Claude Code / Copilot file pair — counterpart derivation, provider field rules, and pair consistency. |
|
||||
| `validation-scripts.md` | Loaded only when a Step 1 script fails or cannot run — scope-detection walk-up, manual fallback checks, and known script failures. |
|
||||
| `field-inventory.md` | Authoritative field lists, read as data by `validate.sh`: valid CC and Copilot agent fields, and the vendor-neutral plugin/APM allowlist. |
|
||||
| `sources.md` | Research provenance records for skill content. Load only when tracing the origin of a specific rule or field constraint. |
|
||||
@@ -10,7 +10,7 @@ source_keys:
|
||||
# Body, Delegation and Comment Discipline Reference
|
||||
|
||||
Upstream source: Claude Code subagent and plugin references, GitHub Copilot custom-agents
|
||||
configuration. House contract: ADR-0020, the context budget.
|
||||
configuration. House contract: the context budget.
|
||||
|
||||
Read this when judging the **body**, **delegation** and **comment-discipline** dimensions.
|
||||
|
||||
@@ -23,8 +23,8 @@ dilutes the signal of what matters.
|
||||
|
||||
## Agents take no body word gate
|
||||
|
||||
ADR-0020 gates a skill body at 600 words SUGGESTION / 900 FAIL and deliberately gates an agent body
|
||||
at nothing. The two are not the same construct: a skill body is loaded into the caller's live
|
||||
A skill body is gated at 600 words SUGGESTION / 900 FAIL; an agent body is deliberately gated at
|
||||
nothing. The two are not the same construct: a skill body is loaded into the caller's live
|
||||
context and competes with the conversation already there, while an agent body *becomes* the system
|
||||
prompt of a fresh context that has nothing else in it. The rationale for the 900-word ceiling does
|
||||
not transfer, so:
|
||||
|
||||
@@ -9,7 +9,7 @@ source_keys:
|
||||
# Agent Description Quality Reference
|
||||
|
||||
Upstream source: Claude Code subagent reference, GitHub Copilot custom-agents configuration.
|
||||
House contract: ADR-0020, the context budget. The house contract is narrower than either
|
||||
House contract: the context budget. The house contract is narrower than either
|
||||
platform's schema rather than a reinterpretation of it: where both speak, both must be satisfied.
|
||||
|
||||
## Why the description is the expensive part
|
||||
|
||||
@@ -90,8 +90,8 @@ Flag as SUGGESTION if:
|
||||
- A rationale is missing from a rule the agent is expected to enforce — present but unexplained
|
||||
- Comments are useful but verbose enough to bury the field they annotate
|
||||
|
||||
**Never report an agent body as too long on a word count.** ADR-0020 gates a skill body at
|
||||
600/900 words and deliberately gates an agent body at nothing, because an agent body *becomes* the
|
||||
**Never report an agent body as too long on a word count.** A skill body is gated at 600/900 words;
|
||||
an agent body is deliberately gated at nothing, because an agent body *becomes* the
|
||||
system prompt of a fresh context rather than competing with a live conversation. No number exists
|
||||
to cite. The one length signal that applies is the Copilot runtime's 30,000-character body limit,
|
||||
which `validate.sh` already reports as a SUGGESTION. Length is judged through the delegation FAIL
|
||||
|
||||
@@ -1,58 +0,0 @@
|
||||
# agent-author
|
||||
|
||||
Creates and improves agent definition files for Claude Code and GitHub Copilot CLI.
|
||||
|
||||
## What it does
|
||||
|
||||
Scaffolds and fills in agent definition files at plugin/APM, project, or user scope. Project and user scope always generate a Claude Code + Copilot CLI file pair (`.md` + `.agent.md`) in one pass. Plugin/APM scope generates a single vendor-neutral `.apm/agents/<name>.agent.md` file instead — no separate Claude Code / Copilot split, since `apm compile` has no per-target field integrator (see ADR-0016). Also applies improvement signals — grill output, inline feedback, session context — to existing agent files. Bumps the version after every change: the resolved package's `apm.yml` at plugin/APM scope (minor for new agents, patch for improvements); project/user scope has no manifest to bump.
|
||||
|
||||
## Before you start
|
||||
|
||||
Have ready: the agent's name (kebab-case), the root directory (plugin root, project root, or `~`), a one-sentence purpose, and the triggering condition (when should the runtime delegate to this agent?).
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/agent-author
|
||||
```
|
||||
|
||||
**Manual scaffold (human workflow):**
|
||||
```bash
|
||||
bash scripts/new-agent.sh <agent-name> <root>
|
||||
|
||||
# Examples:
|
||||
bash scripts/new-agent.sh code-reviewer packages/my-package/ # plugin/APM scope if packages/my-package/apm.yml has a type: field
|
||||
bash scripts/new-agent.sh deploy-assistant .
|
||||
bash scripts/new-agent.sh security-reviewer ~
|
||||
```
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `SKILL.md` | Skill instructions for agents — gotchas, the create/improve dispatch table, the scope dispatch table, the shared gates, and validation/close |
|
||||
| `scripts/new-agent.sh` | Scaffolds agent definition file(s) from templates — a single `.apm/agents/<name>.agent.md` at plugin/APM scope, or a Claude Code + Copilot CLI pair at project/user scope |
|
||||
| `references/create.md` | Create flow: prerequisites, scaffold and scope walk-up, what to fill in, package-root `sources.md` |
|
||||
| `references/improve.md` | Improve flow: signal verification, root-cause grouping, generalizing, delegation over growth, ADR-0020 retrofit |
|
||||
| `references/contract.md` | Description and body contract: three-part description shape, 250/400 tiers, delegation rule in place of a body word gate, invocation axis |
|
||||
| `references/plugin-scope.md` | Plugin/APM scope field rules for the single vendor-neutral file, plus its pre-audit checklist |
|
||||
| `references/project-user-scope.md` | Project/user scope field rules for the Claude Code + Copilot pair, both Copilot formats, plus its pre-audit checklist |
|
||||
| `references/deployment-modes.md` | Scope hierarchy and precedence, scoped identifiers, cache isolation, path conventions |
|
||||
| `references/scripts.md` | Conventions for new-agent.sh and the templates it copies: contract, template variables, file placement, error messages |
|
||||
| `references/sources.md` | Research provenance — sources that informed this skill |
|
||||
| `assets/templates/claude-code.md` | Annotated Claude Code agent definition template (project/user scope) |
|
||||
| `assets/templates/copilot.agent.md.template` | Annotated Copilot CLI agent definition template (project/user scope) |
|
||||
| `assets/templates/apm-agent.md` | Annotated vendor-neutral APM agent definition template (plugin/APM scope) |
|
||||
| `tests/new-agent.bats` | (source-only) bats tests for `scripts/new-agent.sh` |
|
||||
| `assets/README.md` | Directory meta-documentation for assets/ |
|
||||
| `references/README.md` | Directory meta-documentation for references/ |
|
||||
| `scripts/README.md` | Directory meta-documentation for scripts/ |
|
||||
| `tests/README.md` | (source-only) bats dependency instructions and run command |
|
||||
|
||||
Rows marked **(source-only)** exist in the authoring source (`.apm/skills/agent-author/`) but are
|
||||
not present in an installed plugin: `scripts/sync-plugin-content.sh` strips
|
||||
`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
|
||||
plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install. The
|
||||
`assets/templates/` rows above are unaffected — the exclusion is depth-scoped to
|
||||
`<category>/<name>/tests`, so template trees that themselves contain a `tests/` directory ship
|
||||
intact.
|
||||
@@ -6,7 +6,7 @@ description: >
|
||||
Not read-only review -> `agent-audit`. Not skills -> `skill-author`.
|
||||
allowed-tools: Bash Read Write Edit
|
||||
metadata:
|
||||
version: "1.0.1"
|
||||
version: "1.0.2"
|
||||
category: factory
|
||||
source_keys:
|
||||
- context7-websites-code-claude
|
||||
|
||||
@@ -1,55 +0,0 @@
|
||||
---
|
||||
source_keys: []
|
||||
---
|
||||
|
||||
# references/
|
||||
|
||||
## create.md
|
||||
|
||||
The create flow, loaded from SKILL.md Step 1 when no agent file exists at the target path.
|
||||
Covers: prerequisites, the scaffold script and its scope walk-up, what to fill in at every scope,
|
||||
and populating or deleting the package-root `sources.md`.
|
||||
|
||||
## improve.md
|
||||
|
||||
The improve flow, loaded from SKILL.md Step 1 when a file exists and at least one improvement
|
||||
signal is present. Covers: signal verification, partial-pair recovery, root-cause grouping,
|
||||
generalizing rather than patching, delegation over growth, and the ADR-0020 retrofit rule.
|
||||
|
||||
## contract.md
|
||||
|
||||
The description and body contract, loaded from SKILL.md Step 3 before any description is written
|
||||
or any body restructured. Covers: the three-part description shape, banned description content,
|
||||
boundary-target resolution, the 250/400 length tiers, the body role-instruction pattern, the
|
||||
delegation rule that replaces a body word gate, and the invocation axis.
|
||||
|
||||
## plugin-scope.md
|
||||
|
||||
Field rules and the pre-audit checklist for the single vendor-neutral `.apm/agents/<name>.agent.md`
|
||||
file. Loaded from SKILL.md Step 2 when the scaffold resolves plugin/APM scope.
|
||||
|
||||
## project-user-scope.md
|
||||
|
||||
Field rules and the pre-audit checklist for the Claude Code `.md` + Copilot `.agent.md` pair,
|
||||
including the two distinct Copilot formats. Loaded from SKILL.md Step 2 when the scaffold resolves
|
||||
project or user scope.
|
||||
|
||||
## deployment-modes.md
|
||||
|
||||
Scope hierarchy and precedence, scoped identifiers for plugin subdirectory agents, cache isolation
|
||||
behaviour, and Copilot CLI path conventions. Loaded from SKILL.md Step 2 when precedence, paths or
|
||||
cache isolation matter to the run.
|
||||
|
||||
## scripts.md
|
||||
|
||||
Conventions for the `new-agent.sh` scaffold script, the templates it copies, and any future script
|
||||
in this skill. Loaded from `create.md` Step 1 when the script or a template has to change. Covers:
|
||||
the no-interactive-prompts rule, structured output, idempotency, template variables, file
|
||||
placement, error messages, and the no-restated-field-roster rule that `tests/new-agent.bats`
|
||||
enforces.
|
||||
|
||||
## sources.md
|
||||
|
||||
Research provenance record for this skill. Lists the upstream research sources
|
||||
(claude-code-plugins and github-copilot-plugins research docs) that informed SKILL.md and the
|
||||
reference files. Used by `skill-audit` to validate the provenance chain.
|
||||
@@ -6,7 +6,7 @@ source_keys:
|
||||
|
||||
# The agent description and body contract
|
||||
|
||||
House contract, set by ADR-0020. The counts and the boundary targets are enforced by
|
||||
House contract. The counts and the boundary targets are enforced by
|
||||
`agent-audit`'s `scripts/validate.sh`; the prose patterns by the Vale styles it bundles; the
|
||||
judgment calls by its reference files.
|
||||
|
||||
@@ -40,9 +40,8 @@ Banned from a description; move it to the body or to `README.md`:
|
||||
- Restating the same trigger twice in two registers — a verb list, then the same verbs re-quoted
|
||||
as user phrasings. This is a FAIL, not a suggestion.
|
||||
|
||||
**Do not open with an action verb.** "Reviews…", "Analyzes…", "Generates…" was the old house rule
|
||||
and ADR-0020 deleted it: the opener is `Use when`, matching every skill in this corpus, so one
|
||||
router reads one shape.
|
||||
**Do not open with an action verb.** The opener is `Use when`, matching every skill in this corpus,
|
||||
so one router reads one shape.
|
||||
|
||||
**"Use proactively" is Claude Code-only, and conditional even there.** The phrase steers the
|
||||
Claude Code runtime to offer an agent unprompted and does nothing anywhere else, so where it may
|
||||
|
||||
@@ -66,9 +66,10 @@ answer is no.
|
||||
all caps (ALWAYS/NEVER) is usually better reframed as why the behaviour matters, so the agent can
|
||||
apply judgment at the edges.
|
||||
|
||||
**Retrofit before extending.** Any agent predating ADR-0020 has to meet the description contract
|
||||
before any other edit lands — the gates are hot and carry no baseline file, so a one-line fix to a
|
||||
non-compliant agent cannot be committed until its description meets `references/contract.md`.
|
||||
**Retrofit before extending.** Any agent whose description does not meet the contract has to be
|
||||
brought into compliance before any other edit lands — the gates are hot and carry no baseline file,
|
||||
so a one-line fix to a non-compliant agent cannot be committed until its description meets
|
||||
`references/contract.md`.
|
||||
Treat that retrofit as part of the same change, not a follow-up.
|
||||
|
||||
**Re-check the scope rules.** Read the reference for the resolved scope (`SKILL.md` Step 2) and
|
||||
|
||||
@@ -1,22 +0,0 @@
|
||||
# apm-install
|
||||
|
||||
Installs and configures the `apm` (Agent Package Manager) CLI and the agent runtimes it manages.
|
||||
|
||||
## What it does
|
||||
|
||||
Covers the two provisioning steps for working with apm: installing the `apm` binary itself (quick-install script, pinned version, air-gapped mirror, or pip/pipx), and installing/managing an agent runtime apm drives (`apm runtime setup copilot|codex|gemini|llm`, listing installed runtimes, checking which one `apm run` defaults to).
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/apm-install
|
||||
```
|
||||
|
||||
Once `apm` and a runtime are in place, use `apm-workflow` for authoring `apm.yml`, scaffolding packages/marketplaces, compiling, packing, publishing, and auditing.
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `SKILL.md` | Skill instructions for agents |
|
||||
| `references/sources.md` | Provenance chain — research sources that informed this skill |
|
||||
@@ -1,33 +0,0 @@
|
||||
# apm-workflow
|
||||
|
||||
Authors, scaffolds, compiles, and audits apm packages and marketplaces.
|
||||
|
||||
## What it does
|
||||
|
||||
Covers the apm.yml lifecycle a session moves through repeatedly: configuring/scaffolding a package manifest, resolving/fetching its declared dependencies, building or registering a marketplace, compiling/packing/publishing a distributable, and validating integrity via apm audit. Dispatches on the resolved flow to one of five reference files; each carries that flow's traps and names a sibling file where one flow genuinely depends on another's detail.
|
||||
|
||||
## Before you start
|
||||
|
||||
Requires the `apm` binary and (for runtime-driven scripts) an agent runtime already installed — use `apm-install` first if either is missing.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/apm-workflow configure
|
||||
/apm-workflow install
|
||||
/apm-workflow marketplace
|
||||
/apm-workflow compile
|
||||
/apm-workflow audit
|
||||
```
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `SKILL.md` | Dispatch table and the three gotchas common to every branch (MCP secret indirection, the `experimental enable registries` precondition, the unchecked `type:` field) |
|
||||
| `references/configure.md` | apm.yml schema, apm plugin init, dependency forms, MCP secrets, `includes:`, registries; `type:` and `experimental enable registries` traps |
|
||||
| `references/install.md` | apm install, apm install [PACKAGE_REF], --update, --target agent-skills |
|
||||
| `references/marketplace.md` | Building/registering a marketplace, `marketplace add` vs `package add`, package registration, versioning, Claude Code reserved-name/publish-confirm gotchas |
|
||||
| `references/compile.md` | apm compile / pack / publish / run, claude plugin validate agents/ gotcha |
|
||||
| `references/audit.md` | apm audit vs apm audit --ci (they check different things), apm marketplace check, CI wiring, frozen installs, claude plugin validate terminal check |
|
||||
| `references/sources.md` | Provenance chain — research sources that informed this skill |
|
||||
@@ -1,40 +0,0 @@
|
||||
# forge
|
||||
|
||||
Guided entry point for building or improving something in any plugin of this repo when the target artifact type isn't decided yet.
|
||||
|
||||
## What it does
|
||||
|
||||
Grills the user's intent via `grill-with-docs` (inline, interactive) against this repo's `CONTEXT.md` and `docs/adr/`, classifies the target artifact type (skill, agent/subagent definition, plugin, or marketplace entry), announces the classification, then routes to the matching author skill — chaining more than one, in dependency order, if the intent spans multiple artifact types.
|
||||
|
||||
Author-skill invocation defaults to a fork subagent (inherits the grilled-intent context) and falls back to inline when forking isn't possible or the routed flow needs live user interaction (clarifying questions, a HITL gate). After a `skill-author` or `agent-author` route finishes — each already closes out with its own inline audit — forge spins up a separate clean-context subagent to independently re-run the matching audit skill (`skill-audit` / `agent-audit`) as a distinct check on the finished artifact, not a duplicate of the inline one. If that clean audit turns up any unresolved finding, forge loops — re-invoke the author skill to resolve it, re-run the clean audit — until the clean audit comes back with nothing unresolved. `apm-workflow` routes (plugin, marketplace entry) get no recheck: they have no audit counterpart, and no automatic terminal check either — `apm audit` is a separate `apm-workflow` action, not a closing step of the configure or marketplace flow — so forge verifies those routes by reading the written manifest back against the grilled intent.
|
||||
|
||||
## Before you start
|
||||
|
||||
Have a rough idea of what you want to build or change. forge doesn't require you to already know whether it's a skill, agent, plugin, or marketplace entry — that classification is its job.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/forge
|
||||
```
|
||||
|
||||
Skip forge and call the target skill directly (`/skill-author`, `/agent-author`, `/apm-workflow`) when you already know the artifact type.
|
||||
|
||||
## Files
|
||||
|
||||
| File | Loaded when |
|
||||
|------|-------------|
|
||||
| `SKILL.md` | Always — Gotchas, the grill step, the classification dispatch table, and the gates common to every route |
|
||||
| `references/author-routes.md` | The intent classifies as a skill or an agent/subagent definition — fork-vs-inline judgment and the two-tier verification loop |
|
||||
| `references/apm-routes.md` | The intent classifies as a plugin or a marketplace entry — always-inline invocation, why these routes get no clean-context recheck, and the manual read-back that stands in for one |
|
||||
| `references/version-bump.md` | A finished route left the owning package's version unbumped — walk-up rule and the clean-context bump brief |
|
||||
| `references/sources.md` | Never loaded at runtime — provenance chain for the research sources that informed this skill |
|
||||
|
||||
## Routes to
|
||||
|
||||
| Artifact type | Skill |
|
||||
|---|---|
|
||||
| Skill | `skill-author` |
|
||||
| Agent / subagent definition | `agent-author` |
|
||||
| Plugin | `apm-workflow` (configure) |
|
||||
| Marketplace entry | `apm-workflow` (marketplace) |
|
||||
@@ -8,7 +8,7 @@ description: >
|
||||
already named — invoke `skill-author`, `agent-author` or `apm-workflow`
|
||||
directly.
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
version: "1.0.1"
|
||||
category: factory
|
||||
source_keys:
|
||||
- claude-code-subagents-docs
|
||||
|
||||
@@ -28,7 +28,7 @@
|
||||
|
||||
- **URL:** https://agentskills.io/specification.md
|
||||
- **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md
|
||||
- **Description:** Complete SKILL.md format specification — confirms `assets/`, `references/`, and `scripts/` are warranted only by the bulk/reusability of supporting content (large reference material, executable code, templates), not by a skill's category, and forge's per-route procedures are that kind of supporting content — so the spec permits the `references/` split here but does not require it. The warrant is a house decision: ADR-0020's rule that dispatch is mandatory at two or more mutually exclusive flows, which forge's four-row table is. `references/sources.md` likewise exists for this repo's own provenance-chain convention (see `CONTEXT.md`), not because the spec requires it.
|
||||
- **Description:** Complete SKILL.md format specification — confirms `assets/`, `references/`, and `scripts/` are warranted only by the bulk/reusability of supporting content (large reference material, executable code, templates), not by a skill's category, and forge's per-route procedures are that kind of supporting content — so the spec permits the `references/` split here but does not require it. The warrant is a house decision: dispatch is mandatory at two or more mutually exclusive flows, which forge's four-row table is. `references/sources.md` likewise exists for this repo's own provenance-chain convention (see `CONTEXT.md`), not because the spec requires it.
|
||||
- **Contributing files:** SKILL.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
|
||||
@@ -1,53 +0,0 @@
|
||||
# skill-audit
|
||||
|
||||
Audit a skill directory against the agentskills.io specification and the house context-budget contract (ADR-0020). Runs structural validation then a qualitative review across description quality, body discipline, patterns, formatting, file structure, scripts, and internal consistency, plus a provenance chain check.
|
||||
|
||||
## What it does
|
||||
|
||||
1. Runs `scripts/validate.sh` and `scripts/validate-provenance.sh` for structural and provenance checks, plus `scripts/vale-wrap.sh` — a Vale prefilter that deterministically flags non-imperative description openers, composition and architecture notes, vague wording, padding phrases, and "There is/are" sentence openers
|
||||
2. Reads all files in the skill directory
|
||||
3. Applies qualitative checks across five dimension groups — always loading `references/finding-criteria.md`, then one rubric from `references/` per group the criteria put in play
|
||||
4. Outputs a compact findings report — findings only, grouped by dimension, each with Why and Fix — and a result block with handoff to `skill-author`
|
||||
|
||||
`validate.sh` enforces two independent length families that must not be conflated: the agentskills.io spec conformance ceilings (500 lines, 2,770 words, both counting the whole file) and the ADR-0020 context budget (250/400 description characters, 600/900 body-only words).
|
||||
|
||||
Alongside those it runs shape checks that are not length measurements at all. Three are FAILs: every routing target named in the description — in the compressed `Not <thing> -> <name>` arrow **and** in the prose form — must resolve to a real skill or agent; every `references/<file>.md` the body names must exist on disk; and `metadata.version` must be present and three-part semver (ADR-0022). That last one is FAIL rather than SUGGESTION because the `skill-frontmatter` pre-commit hook rejects the file without it — an audit grading it lower would report ready-to-ship on a file the commit gate refuses. Three are SUGGESTIONs: a missing boundary clause, a Gotchas section over five entries, and a Gotchas section over 25% of the body. The resolution universe for boundary targets is derived by walking up from the audited `SKILL.md` — the authoring root above it, its own apm package, and that package's declared `apm.yml` dependencies — so a fresh clone and a machine that has run `apm install` return the same verdict. When no universe can be determined the check prints `INFO ... DID NOT RUN` and does not silently pass.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/skill-audit
|
||||
```
|
||||
|
||||
Provide the path to the skill directory to audit when invoking.
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `SKILL.md` | Skill instructions for agents |
|
||||
| `scripts/validate.sh` | Structural validator — checks name format, name matches directory, description presence and length, `metadata.version` presence and semver shape (ADR-0022), body-only word count, line and whole-file word ceilings, boundary-clause presence, boundary-target resolution, `references/` pointer existence, Gotchas entry count and body share, placeholder detection, script executable bit, and interactive-prompt detection |
|
||||
| `scripts/validate-provenance.sh` | Provenance validator — checks sources.md completeness, source_keys/slug consistency, Contributing files existence, bidirectional linkage, Research doc: fields, upstream research doc alignment, and (check 9, INFO only) whether a slug's `Description` or `Contributing files` text has changed since a base ref — `--base-ref=<ref>` or `VALIDATE_PROVENANCE_BASE_REF`, defaulting to the merge base with `origin/main` |
|
||||
| `scripts/vale-wrap.sh` | Vale prefilter wrapper — runs the bundled `Kyberforge` Vale styles against SKILL.md and reports alerts as deterministic FAILs ahead of Step 3's qualitative review |
|
||||
| `assets/vale/.vale.ini` | Vale configuration — points Vale at the bundled `Kyberforge` style path, self-located relative to `vale-wrap.sh` |
|
||||
| `assets/vale/styles/Kyberforge/CompositionNote.yml` | Vale rule — flags composition and architecture notes in a description (e.g. "cross-cutting", "entry point", "rather than duplicating") |
|
||||
| `assets/vale/styles/Kyberforge/DescriptionOpener.yml` | Vale rule — flags non-imperative "This..." description openers |
|
||||
| `assets/vale/styles/Kyberforge/PaddingPhrase.yml` | Vale rule — flags generic "see references/" padding phrasing in conditional references |
|
||||
| `assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml` | Vale rule — flags body sentences starting with "There is"/"There are" |
|
||||
| `assets/vale/styles/Kyberforge/VagueWording.yml` | Vale rule — flags known filler wording (e.g. "helps with", "utilize") |
|
||||
| `references/finding-criteria.md` | Every dimension's FAIL and SUGGESTION criteria — the one Step 3 file loaded on every run; it decides which rubrics below are worth loading |
|
||||
| `references/description-quality.md` | Rubric for the description dimension — why the description is the expensive part, the hand-invoked (`disable-model-invocation`) contract, the three-part shape, when an indirect trigger is warranted, near-miss exclusions, and a before/after pair |
|
||||
| `references/body-discipline.md` | Rubric for the body-discipline dimension — the core test, the 600/900 body-only budget against the 2,770-word whole-file backstop, the mandatory-dispatch rule, and the Gotchas constraints |
|
||||
| `references/patterns.md` | Rubric for the patterns dimension — which instruction construct fits which job, and how each is correctly formed |
|
||||
| `references/file-structure.md` | Rubric for the file-structure and internal-consistency dimensions — permitted directories, cross-plugin path rules and their two structural exemptions, README drift |
|
||||
| `references/formatting-and-scripts.md` | Rubric for the formatting and scripts dimensions — heading and fencing conventions, and the agentic-use criteria for bundled scripts |
|
||||
| `references/validation-scripts.md` | Step 1 troubleshooting — the manual structural fallback when `validate.sh` cannot run, and the script exit codes that are easy to misread (loaded on a script failure, and on any exit-0 run that printed something — `validate-provenance.sh`'s check 9 is INFO-only, so its findings arrive that way) |
|
||||
| `references/sources.md` | Provenance record — agentskills.io sources that informed this skill and which files each contributed to |
|
||||
| `tests/validate.bats` | (source-only) Bats test suite for validate.sh |
|
||||
| `tests/validate-provenance.bats` | (source-only) Bats test suite for validate-provenance.sh |
|
||||
| `tests/README.md` | (source-only) Setup instructions for bats-support and bats-assert test dependencies |
|
||||
|
||||
Rows marked **(source-only)** exist in the authoring source (`.apm/skills/skill-audit/`) but are
|
||||
not present in an installed plugin: `scripts/sync-plugin-content.sh` strips
|
||||
`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
|
||||
plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install.
|
||||
@@ -7,7 +7,7 @@ description: >
|
||||
skill-author.
|
||||
allowed-tools: Bash Read
|
||||
metadata:
|
||||
version: "1.0.1"
|
||||
version: "1.0.2"
|
||||
category: factory
|
||||
source_keys:
|
||||
- agentskills-home
|
||||
@@ -50,7 +50,7 @@ Read `references/validation-scripts.md` when any of the three cannot run or exit
|
||||
|
||||
## Step 2 — Read the whole skill
|
||||
|
||||
Read `SKILL.md`, `README.md`, and every text file under `scripts/`, `references/`, `assets/` and `tests/`. Skip binaries only — internal-consistency findings need the full picture.
|
||||
Read `SKILL.md` and every text file under `scripts/`, `references/`, `assets/` and `tests/`. Skip binaries only — internal-consistency findings need the full picture.
|
||||
|
||||
## Step 3 — Qualitative audit
|
||||
|
||||
@@ -64,7 +64,7 @@ Read `references/finding-criteria.md` first — every dimension's FAIL and SUGGE
|
||||
| file-structure, internal-consistency | `references/file-structure.md` |
|
||||
| formatting, scripts | `references/formatting-and-scripts.md` |
|
||||
|
||||
Each rubric is self-contained and grounded in the agentskills.io specification plus the house context budget (ADR-0020). Cite file and line number for every finding.
|
||||
Each rubric is self-contained and grounded in the agentskills.io specification plus the house context budget. Cite file and line number for every finding.
|
||||
|
||||
## Step 4 — Report
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@ source_keys:
|
||||
# Body Discipline Reference
|
||||
|
||||
Upstream source: agentskills.io — skill-authoring, best-practices.
|
||||
House contract: ADR-0020, the context budget.
|
||||
House contract: the context budget.
|
||||
|
||||
## The core test
|
||||
|
||||
@@ -31,7 +31,7 @@ Include content the agent lacks:
|
||||
Move to `references/`, behind an explicit "If X, read `references/<file>.md`" trigger — the literal
|
||||
conditional form, never a generic pointer. Write the real filename in the skill under audit; the
|
||||
angle brackets are a placeholder here, and a literal `references/file.md` in a body is an ERROR
|
||||
from the ADR-0020 gate because no such file exists on disk.
|
||||
from the gate because no such file exists on disk.
|
||||
|
||||
**A dispatch table satisfies this requirement on its own.** A table row already pairs a condition
|
||||
with a target, which is exactly what the literal form encodes; restating each row underneath as a
|
||||
@@ -60,7 +60,7 @@ Do not conflate these, and do not report them as one finding.
|
||||
|
||||
| Gate | SUGGESTION | FAIL | Counts |
|
||||
|---|---|---|---|
|
||||
| Body budget (house, ADR-0020) | 600 words | 900 words | the **body only** — everything after the frontmatter's closing `---` |
|
||||
| Body budget (house) | 600 words | 900 words | the **body only** — everything after the frontmatter's closing `---` |
|
||||
| Spec conformance (agentskills.io) | — | 2,770 words / 500 lines | the **whole file**, frontmatter included |
|
||||
|
||||
The 2,770-word ceiling is a token-conformance backstop calibrated to the densest prose in the
|
||||
@@ -134,7 +134,7 @@ Constraints:
|
||||
|
||||
Worked negative example — **`git-commits` v0.1.2 at commit `5e23250`, a fixed pre-retrofit
|
||||
snapshot, not the current file.** The live skill is v0.1.3 and matches none of the citations below;
|
||||
they are quoted as they stood before the ADR-0020 retrofit, and are not to be refreshed against
|
||||
they are quoted as they stood in that snapshot, and are not to be refreshed against
|
||||
`HEAD`. The snapshot is reachable only from a checkout of the authoring repo — an installed plugin
|
||||
cache holds no git history and no such path — so read the citations below as quoted rather than
|
||||
going to look for the file. From a checkout:
|
||||
|
||||
@@ -7,7 +7,7 @@ source_keys:
|
||||
# Description Quality Reference
|
||||
|
||||
Upstream source: agentskills.io — optimizing-descriptions, specification.
|
||||
House contract: ADR-0020, the context budget. The house contract is narrower than the spec
|
||||
House contract: the context budget. The house contract is narrower than the spec
|
||||
rather than a reinterpretation of it: where both speak, both must be satisfied.
|
||||
|
||||
## Why the description is the expensive part
|
||||
|
||||
@@ -19,7 +19,6 @@ knows to look at. Flag any other directory as a FAIL.
|
||||
`test_*.sh`) there are a FAIL — they belong in `tests/`.
|
||||
- No non-spec files at the skill root: no `META.md`, no stray config outside the four directories.
|
||||
- An optional directory that exists must hold real content, not an unfilled placeholder README.
|
||||
- `README.md` is present and describes the skill and its files accurately.
|
||||
|
||||
## Cross-plugin path references
|
||||
|
||||
@@ -41,7 +40,7 @@ Resolve before flagging, twice over:
|
||||
**Referring to another skill's file.** There is one sanctioned spelling, and it is possessive:
|
||||
`skill-audit's references/validation-scripts.md`. Write the skill by name and let the reader
|
||||
resolve it — do not spell the repo path. The full path is the thing this section forbids, and
|
||||
`references/validation-scripts.md` on its own is a hard ERROR from the ADR-0020 gate, which
|
||||
`references/validation-scripts.md` on its own is a hard ERROR from the gate, which
|
||||
requires an unqualified `references/` pointer to exist in the skill's OWN directory. The
|
||||
possessive form is the only spelling both rules accept; the gate recognises it and skips the
|
||||
on-disk check. Flag any other spelling of a cross-skill reference.
|
||||
@@ -59,17 +58,12 @@ Two directories are exempt, and the exemptions are structural rather than discre
|
||||
|
||||
## Internal consistency
|
||||
|
||||
The skill has to agree with itself. Three checks:
|
||||
The skill has to agree with itself. Two checks:
|
||||
|
||||
- `SKILL.md`'s steps match what the scripts actually do — the arguments, the exit codes, and the
|
||||
output shape it tells the agent to expect.
|
||||
- `README.md`'s file table lists every file that exists, with no missing rows and no stale rows for
|
||||
files since deleted.
|
||||
- Placeholder READMEs inside `scripts/`, `references/` and `assets/` say the same thing about each
|
||||
- Placeholder READMEs inside `scripts/`, `tests/` and `assets/` say the same thing about each
|
||||
directory that `SKILL.md` does.
|
||||
|
||||
A stale README row is the most common finding here and the easiest to miss from inside an
|
||||
authoring pass, because the author knows what was intended and reads it into the gap.
|
||||
|
||||
The FAIL and SUGGESTION criteria for this dimension live in `references/finding-criteria.md`,
|
||||
which Step 3 loads on every run.
|
||||
|
||||
@@ -111,13 +111,11 @@ Flag as FAIL if:
|
||||
- A path that resolves outside the skill directory appears outside the two exempt locations, in
|
||||
prose rather than in a fenced example
|
||||
- `tests/` exists but `tests/README.md` is missing or does not document its repo-level dependency
|
||||
- `README.md` is absent, or its file table has a missing or stale row
|
||||
- `SKILL.md` describes a script invocation the script does not accept
|
||||
|
||||
Flag as SUGGESTION if:
|
||||
|
||||
- An optional directory exists but holds only a placeholder README
|
||||
- `README.md` is accurate but describes a file's purpose more thinly than `SKILL.md` does
|
||||
|
||||
## formatting and scripts — `references/formatting-and-scripts.md`
|
||||
|
||||
|
||||
@@ -40,7 +40,7 @@ If the API returns a non-200 status, read `references/api-errors.md`.
|
||||
```
|
||||
|
||||
That block is fenced because the filename in it is illustrative — an unfenced `references/` pointer
|
||||
in a `SKILL.md` body must resolve on disk or the ADR-0020 gate reports a hard ERROR. The generic
|
||||
in a `SKILL.md` body must resolve on disk or the gate reports a hard ERROR. The generic
|
||||
form — pointing at the directory and hoping — defeats
|
||||
progressive disclosure, because the agent either loads everything or loads nothing.
|
||||
`Kyberforge.PaddingPhrase` catches the common generic phrasing deterministically; other malformed
|
||||
|
||||
@@ -21,7 +21,7 @@ have checked, and the Step 4 coverage line then names a dimension nothing actual
|
||||
## Manual structural fallback
|
||||
|
||||
`validate.sh` needs `python3` **and** PyYAML, and refuses to start without either — the description
|
||||
value has to be measured after YAML folding is resolved, so skipping the ADR-0020 gates would be a
|
||||
value has to be measured after YAML folding is resolved, so skipping these gates would be a
|
||||
vacuous pass rather than a partial one. The two are checked separately, so the message already names
|
||||
the right one — report it verbatim rather than diagnosing further:
|
||||
|
||||
@@ -40,14 +40,14 @@ by hand and file the results under `### Structure` exactly as the script's outpu
|
||||
session, so a skill without one can never be routed to.
|
||||
- **Description length**, measured on the folded YAML value with newlines collapsed to single
|
||||
spaces — not on the raw block scalar, which counts indentation. 250 characters SUGGESTION, 400
|
||||
FAIL (ADR-0020), 1,024 FAIL (agentskills.io spec).
|
||||
FAIL (house), 1,024 FAIL (agentskills.io spec).
|
||||
- **Body length**, counting everything after the frontmatter's closing `---`. 600 words
|
||||
SUGGESTION, 900 FAIL (ADR-0020).
|
||||
SUGGESTION, 900 FAIL (house).
|
||||
- **Whole-file ceilings**, counting the file including frontmatter: 500 lines FAIL, 2,770 words
|
||||
FAIL (agentskills.io spec). These are a different measurement from the two above — report them
|
||||
as separate findings, never merged.
|
||||
- **A boundary clause is present** — either the prose form (`do not` / `instead` / `rather than` /
|
||||
`not for`) or ADR-0020's compressed `Not <thing> -> <name>` arrow. **SUGGESTION**, not FAIL:
|
||||
`not for`) or the compressed `Not <thing> -> <name>` arrow. **SUGGESTION**, not FAIL:
|
||||
the absence is deterministic, but whether this skill warrants one is the auditor's call.
|
||||
- **Boundary targets resolve** — **FAIL** on a name that resolves to nothing. See the section
|
||||
below; resolving these by hand is the one item on this list with a procedure of its own.
|
||||
|
||||
@@ -1,74 +0,0 @@
|
||||
# skill-author
|
||||
|
||||
Author and refine skills conforming to the [agentskills.io](https://agentskills.io) specification — create new skills from scratch or apply improvement signals to existing ones.
|
||||
|
||||
## What it does
|
||||
|
||||
Routes to one of two flows based on context: if no skill directory exists at the target path, it scaffolds the directory from annotated templates, fills in `SKILL.md` and supporting files, and validates the result. If an existing skill directory and improvement signals are both present, it groups those signals by root cause and applies targeted edits, then re-validates. In both flows, bumps the skill's `metadata.version` — minor for create, patch for improve — which every skill carries (ADR-0022).
|
||||
|
||||
`SKILL.md` itself carries only the dispatch table, the invocation-axis decision, the contract gates and the shared close; each flow lives in its own self-contained reference file, per ADR-0020.
|
||||
|
||||
## The contract it teaches
|
||||
|
||||
Authored skills are held to the ADR-0020 context budget. A description carries a trigger clause, at most one capability clause, and a boundary clause of the form `Not <thing> -> <skill-name>` whose target must resolve to a real skill or agent — 250 characters target, 400 hard ceiling. A body carries the decision procedure only — 600 words target, 900 hard ceiling, counting the body alone, which is a separate measurement from the 2,770-word / 500-line whole-file spec backstop. Skills with two or more mutually exclusive flows must dispatch. `references/contract.md` holds the full rules; `assets/templates/SKILL.md` encodes them as a fill-in skeleton.
|
||||
|
||||
Before a description is written, the skill asks whether the target is model-invoked or hand-invoked. A hand-invoked skill sets `disable-model-invocation: true` and carries one plain human-facing sentence with no trigger list.
|
||||
|
||||
## Before you start
|
||||
|
||||
- Run `/grill-me` to resolve design decisions before creating a new skill
|
||||
- Collect domain research, examples, and constraints
|
||||
- Know the skill name (kebab-case) and destination path
|
||||
|
||||
## Placement
|
||||
|
||||
`scripts/new-skill.sh` resolves the mode automatically by walking up from the given path — see `references/create.md` Step 1 for the full algorithm.
|
||||
|
||||
| Mode | Path | Chosen when |
|
||||
|------|------|-------------|
|
||||
| Standalone | `<path>/<name>/` | No `apm.yml` with a top-level `type:` field is found walking up from `<path>`, before hitting `.git` or the filesystem root |
|
||||
| Package (APM) | `<package-root>/.apm/skills/<name>/` | A type-bearing `apm.yml` is found at or above `<path>` — `<path>` just needs to be somewhere inside the package |
|
||||
|
||||
If the destination resolves inside an APM package, read `references/deployment-modes.md` — self-containment rules apply to `apm compile` output the same way they applied to plugin cache isolation.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/skill-author
|
||||
```
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `README.md` | Human-readable overview of the skill and its files |
|
||||
| `SKILL.md` | Skill instructions for agents |
|
||||
| `scripts/new-skill.sh` | Walks up from the given path to resolve package vs standalone mode, then copies annotated templates to the resolved destination |
|
||||
| `references/create.md` | The create flow end to end — prerequisites, package-intent gate, scaffold, frontmatter, scripts, references, sources (loaded on demand) |
|
||||
| `references/improve.md` | The improve flow end to end — signal verification, root-cause grouping, announcement, edits (loaded on demand) |
|
||||
| `references/contract.md` | The ADR-0020 description and body contract, the Gotchas constraint, the two size gates, body patterns, and org-policy embedding (loaded on demand) |
|
||||
| `references/retrofit.md` | Bringing a pre-ADR-0020 skill into contract — ordered cut procedure, the mutually-exclusive-flows test, reference-file conventions, the collateral checklist, and a worked description retrofit (loaded from the improve flow when a budget is exceeded) |
|
||||
| `references/deployment-modes.md` | APM package vs standalone differences and self-containment/cache-isolation rules (loaded on demand) |
|
||||
| `references/scripts.md` | Package runners, inline dependency patterns, and full script contract (loaded on demand) |
|
||||
| `references/sources.md` | Upstream research sources and which skill files each contributed to |
|
||||
| `assets/templates/SKILL.md` | Annotated SKILL.md template — emits an ADR-0020-compliant description and body skeleton |
|
||||
| `assets/templates/README.md` | Annotated README template for the new skill |
|
||||
| `assets/templates/scripts/README.md` | Placeholder for bundled scripts |
|
||||
| `assets/templates/references/README.md` | Placeholder for reference docs |
|
||||
| `assets/templates/references/sources.md` | Sources provenance template for new skills |
|
||||
| `assets/templates/assets/README.md` | Placeholder for static assets |
|
||||
| `assets/templates/tests/README.md` | Placeholder for test files |
|
||||
| `tests/new-skill.bats` | (source-only) Bats test suite for `scripts/new-skill.sh` |
|
||||
| `tests/README.md` | (source-only) Setup instructions for bats-support and bats-assert test dependencies |
|
||||
|
||||
Rows marked **(source-only)** exist in the authoring source (`.apm/skills/skill-author/`) but are
|
||||
not present in an installed plugin: `scripts/sync-plugin-content.sh` strips
|
||||
`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
|
||||
plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install. The
|
||||
`assets/templates/tests/README.md` row above is **not** source-only — the exclusion is depth-scoped
|
||||
to `<category>/<name>/tests`, so the scaffolding template tree ships intact, which
|
||||
`scripts/new-skill.sh` depends on at runtime.
|
||||
|
||||
## Spec reference
|
||||
|
||||
[agentskills.io specification](https://agentskills.io/specification.md)
|
||||
@@ -6,7 +6,7 @@ description: >
|
||||
Not read-only review -> `skill-audit`. Not agent files -> `agent-author`.
|
||||
allowed-tools: Bash Read Write Edit
|
||||
metadata:
|
||||
version: "1.0.1"
|
||||
version: "1.0.2"
|
||||
category: factory
|
||||
source_keys:
|
||||
- agentskills-home
|
||||
|
||||
@@ -1,51 +0,0 @@
|
||||
# SKILL_NAME
|
||||
|
||||
<!-- FILL IN: One sentence describing what this skill does. -->
|
||||
|
||||
## What it does
|
||||
|
||||
<!-- FILL IN: 2–4 sentences. What task does this skill handle?
|
||||
What does the agent produce or accomplish when it runs? -->
|
||||
|
||||
## Before you start
|
||||
|
||||
<!-- FILL IN: List any prerequisites the user should have ready.
|
||||
Examples: research docs, a grill session, specific input files, credentials.
|
||||
Delete this section if the skill has no meaningful prerequisites. -->
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/SKILL_NAME
|
||||
```
|
||||
|
||||
<!-- FILL IN: Add any required or common arguments.
|
||||
If the skill takes no arguments, delete the code block above and just keep the slash command. -->
|
||||
|
||||
<!-- OPTIONAL: Manual (human) workflow — include if the skill bundles scripts a human can run directly.
|
||||
|
||||
**Manual workflow:**
|
||||
```bash
|
||||
# FILL IN: step-by-step commands
|
||||
```
|
||||
-->
|
||||
|
||||
## Files
|
||||
|
||||
<!-- FILL IN: List each file individually. Remove rows for directories you deleted.
|
||||
Replace the example rows below with your actual files. -->
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `SKILL.md` | Skill instructions for agents |
|
||||
| `scripts/your-script.sh` | FILL IN: what this script does |
|
||||
| `references/your-doc.md` | FILL IN: what this reference covers |
|
||||
| `assets/your-asset.json` | FILL IN: what this asset is |
|
||||
| `tests/your-test.bats` | FILL IN: what this test covers |
|
||||
|
||||
<!-- OPTIONAL: Spec reference — include if this skill implements or follows an external standard.
|
||||
|
||||
## Spec reference
|
||||
|
||||
[FILL IN: Spec name](FILL IN: URL)
|
||||
-->
|
||||
@@ -1,39 +0,0 @@
|
||||
# references/
|
||||
|
||||
Additional documentation agents load on demand. Files here extend SKILL.md
|
||||
without bloating its core context.
|
||||
|
||||
## When to add a reference file
|
||||
|
||||
The SKILL.md body carries the decision procedure only. Everything else lives
|
||||
here: lookup tables, spec restatements, output schemas, templates, example
|
||||
blocks, rationale prose, and anything only one branch reaches.
|
||||
|
||||
Two triggers make a reference file mandatory rather than optional:
|
||||
|
||||
- The body is over its 600-word target (900 is a hard failure), counting the
|
||||
body only — everything after the frontmatter's closing `---`.
|
||||
- The skill has two or more mutually exclusive flows. The body then keeps only
|
||||
a dispatch table plus the gates common to every branch, and each flow gets
|
||||
its own self-contained file here (e.g. `create.md`, `improve.md`).
|
||||
|
||||
## How to reference from SKILL.md
|
||||
|
||||
Load conditionally — tell the agent exactly when to read each file:
|
||||
|
||||
```markdown
|
||||
If the API returns a non-200 status, read `references/api-errors.md`.
|
||||
```
|
||||
|
||||
Avoid generic "see references/ for details" — the agent loads context on
|
||||
demand, so give it a precise trigger condition.
|
||||
|
||||
## File conventions
|
||||
|
||||
- One topic per file — focused files mean less unnecessary context loaded
|
||||
- Kebab-case filenames (e.g. `api-errors.md`, `output-formats.md`)
|
||||
- Keep files under 200 lines where possible
|
||||
|
||||
## If no reference files are needed
|
||||
|
||||
Delete this README and the `references/` directory entirely.
|
||||
@@ -7,7 +7,7 @@ source_keys:
|
||||
|
||||
# The description and body contract
|
||||
|
||||
House contract, set by ADR-0020. Every rule here is enforced by `/skill-audit` —
|
||||
House contract. Every rule here is enforced by `/skill-audit` —
|
||||
`scripts/validate.sh` for the counts and the boundary targets, the bundled Vale styles for the
|
||||
prose patterns, and its reference files for the judgment calls.
|
||||
|
||||
|
||||
@@ -84,7 +84,7 @@ already covers the new skill. Use Read/Edit directly on `apm.yml`; this is not p
|
||||
## 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 ADR-0020 body skeleton and the two frontmatter
|
||||
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.
|
||||
|
||||
@@ -71,23 +71,16 @@ outperforms an exhaustive one.
|
||||
writing a rule in all caps (ALWAYS/NEVER), reframe it: explain why the behavior matters so the
|
||||
agent can apply judgment in edge cases.
|
||||
|
||||
**Retrofit before extending.** Any edit to a skill that predates ADR-0020 has to bring it into the
|
||||
contract first — the gates are hot and carry no baseline file, so a one-line fix to a
|
||||
**Retrofit before extending.** Any edit to a skill that does not meet the contract has to bring it
|
||||
into compliance first — the gates are hot and carry no baseline file, so a one-line fix to a
|
||||
non-compliant skill cannot be committed until the description and body meet
|
||||
`references/contract.md`. Treat that retrofit as part of the same change, not a follow-up.
|
||||
|
||||
If the skill's description exceeds 250 characters, or its body-only word count exceeds 600, read
|
||||
`references/retrofit.md` before editing. It carries the ordered cut procedure, the
|
||||
mutually-exclusive-flows test, the reference-file conventions this flow needs, the collateral
|
||||
checklist for `README.md` and `references/sources.md`, and a worked description retrofit. Do not
|
||||
improvise the cuts — four dry runs invented six to ten different answers to the same questions.
|
||||
|
||||
If a signal points to a script or reference file, edit that file directly rather than adding a
|
||||
workaround in SKILL.md.
|
||||
|
||||
**A skill carrying no `metadata.version` is seeded at `"1.0.0"`, not bumped** — `SKILL.md` Step 4's
|
||||
patch bump presumes a version to bump, and ADR-0022 reserves `"0.1.0"` for a newly created skill.
|
||||
`references/retrofit.md` carries the reasoning.
|
||||
|
||||
**Check for regressions before handing back.** `SKILL.md` Step 4 tells you to resolve every FAIL,
|
||||
which says nothing about a check that passed *before* these edits and no longer does. Compare the
|
||||
|
||||
@@ -1,197 +0,0 @@
|
||||
---
|
||||
source_keys:
|
||||
- agentskills-best-practices
|
||||
- agentskills-optimizing-descriptions
|
||||
---
|
||||
|
||||
# Retrofitting a skill to the ADR-0020 contract
|
||||
|
||||
Read this when `references/improve.md` Step 4 sends you here: the skill you are editing is over
|
||||
the description or body budget and has to come into contract before any other change can be
|
||||
committed. The gates are hot and carry no baseline file, so a one-line fix to a non-compliant
|
||||
skill is blocked until this is done.
|
||||
|
||||
Measure first. Do not guess which gate fired: run `/skill-audit` on the directory and read its
|
||||
`### Structure` dimension, which reports the description characters and the **body-only** word
|
||||
count separately from the whole-file spec backstop. Retrofit against the number that actually
|
||||
fired — a skill can sit a thousand words inside the whole-file backstop while failing the body
|
||||
budget.
|
||||
|
||||
**Validate in place.** Audit the skill's real directory inside its package. Never audit a copy in a
|
||||
scratch directory, and never move a skill out to work on it: the boundary-target universe is built
|
||||
by walking up *from the file being checked*, so a copy with no authoring root above it resolves
|
||||
against nothing and the check declines rather than running —
|
||||
|
||||
```text
|
||||
INFO boundary-target resolution DID NOT RUN — no skill universe could be determined for
|
||||
this path ... Unchecked target(s): totally-fake-target
|
||||
```
|
||||
|
||||
The run still exits 0, so that line reads as a pass and is not one. Treat `DID NOT RUN` as **not
|
||||
checked**, always. A retrofit signed off on a scratch copy carries an unverified boundary target
|
||||
into the corpus, which is precisely the failure this gate exists to catch.
|
||||
|
||||
## Cut in this order
|
||||
|
||||
Work the list top down and stop as soon as the gate clears. The order is by ratio of tokens
|
||||
removed to behaviour lost — inverting it is how a retrofit ends up deleting the one instruction
|
||||
the skill existed to carry.
|
||||
|
||||
1. **Gotchas that paraphrase a step in the body below.** Zero information, and already a FAIL on
|
||||
its own. Delete the Gotcha, keep the step.
|
||||
2. **Spec restatements** — text that repeats a published specification, a tool's `--help`, or a
|
||||
ceiling the validator already enforces. The agent gets this right without it. Delete, or move
|
||||
the table to `references/` if a flow genuinely needs to look it up.
|
||||
3. **Capability enumeration** — in a description, the feature list after the trigger clause; in a
|
||||
body, the paragraph that recites what the skill can do. One capability clause survives in the
|
||||
description; the rest belongs in `README.md`.
|
||||
4. **Per-flow prose** — anything only one branch of the procedure ever reaches. This is the
|
||||
largest single win in most bodies, and it is a *move*, not a delete: each flow gets its own
|
||||
self-contained `references/` file, wired from a dispatch table.
|
||||
|
||||
If the body is still over after all four, the skill is doing two jobs. Split it, and say so
|
||||
rather than compressing prose until it stops being readable.
|
||||
|
||||
## What "mutually exclusive flows" means
|
||||
|
||||
Two or more flows that a single invocation cannot both take. The three-way test, copied verbatim
|
||||
from the body-discipline rubric `/skill-audit` judges against — nothing to load, it is quoted in
|
||||
full here:
|
||||
|
||||
> separate subcommands, separate input types, separate lifecycle stages
|
||||
|
||||
Any one of the three is enough. Two flows that differ only in a parameter value are one flow.
|
||||
At two or more mutually exclusive flows a dispatch table is **mandatory** regardless of word
|
||||
count, because every invocation otherwise pays for every branch it did not take.
|
||||
|
||||
## Reference-file conventions
|
||||
|
||||
The create flow owns these rules, and this flow is forbidden from reading `references/create.md`,
|
||||
so what a retrofit needs is restated here:
|
||||
|
||||
- **One topic per file.** A file mixing two concerns gets loaded for one of them and spends the
|
||||
caller's context on the other.
|
||||
- **Kebab-case filenames**, named after the topic rather than the flow that reads it —
|
||||
`body-discipline.md`, not `step-3.md`.
|
||||
- **Wire every file with the literal conditional form** ``If <condition>, read
|
||||
`references/<file>.md` ``. A generic pointer ("see `references/` for details") is a Vale error.
|
||||
- **Two hops from `SKILL.md`, never three.** A flow file may route on to a shared contract file;
|
||||
a file reachable only through two intermediates is rarely loaded when it is needed.
|
||||
- **`source_keys` frontmatter.** If the content you are moving drew on a research source, the new
|
||||
file needs top-level `source_keys:` frontmatter listing those slugs, and every slug must already
|
||||
exist as an `## <slug>` heading in `references/sources.md`. Moving sourced content out of
|
||||
`SKILL.md` without carrying its slugs across breaks the provenance chain, and `/skill-audit`
|
||||
reports the new file as an INFO with no `source_keys`.
|
||||
|
||||
## Collateral is mandatory, not optional
|
||||
|
||||
Moving content out of a `SKILL.md` leaves three files describing a structure that no longer
|
||||
exists. `/skill-audit`'s provenance check exits clean on all three of these, so nothing catches
|
||||
them for you. After every retrofit that adds, removes or renames a file:
|
||||
|
||||
- [ ] **`README.md` file table** — a row for every new `references/` file, and no row left for a
|
||||
file that is gone. Say what triggers the load, not just what the file contains.
|
||||
- [ ] **`references/README.md`**, where the skill has one — same update, same reason.
|
||||
- [ ] **`references/sources.md` → `Contributing files`** — add the new file to every slug whose
|
||||
content moved into it, and remove any file the retrofit deleted. This is the one that gets
|
||||
missed: `sources.md` keeps citing sections of `SKILL.md` that no longer exist, the
|
||||
provenance check still exits 0, and the stale claim survives review.
|
||||
- [ ] **Reachability of every relocated gate.** For each Gotcha or gate the retrofit moved out of
|
||||
the body, list the flows that need it and confirm each one reaches the surviving copy. A gate
|
||||
that lands in a single flow file is invisible to every other branch, and no gate detects
|
||||
that: `/skill-audit` reads whichever file it was handed, and the word counts improve either
|
||||
way. Where more than one flow needs it, the copy belongs in the body's common-gates section,
|
||||
not in a flow file. Grep the skill for the gate's key term and check every branch that hits
|
||||
zero.
|
||||
- [ ] Re-run `/skill-audit` and confirm its `### Provenance` dimension does not report the new
|
||||
file as missing `source_keys`.
|
||||
|
||||
## Compression must not add authority the source text didn't have
|
||||
|
||||
This one is **not** part of the checklist above, and deliberately so: it fires on a wording change
|
||||
with no file change at all, so a retrofit that adds and removes nothing still owes it.
|
||||
|
||||
The `sources.md` bullet above is about an entry going *stale* — Contributing files left uncited
|
||||
after content moves. This is a distinct failure: a compression or rewrite pass that upgrades an
|
||||
honest hedge in a Description into an unsupported confident claim, without the underlying source
|
||||
having changed at all — "no forge-specific content drawn directly from it beyond that" quietly
|
||||
becoming "Grounds Step 2's dispatch table."
|
||||
|
||||
`/skill-audit`'s provenance script does now notice this class: it diffs each slug's `Description`
|
||||
and `Contributing files` text against a base ref and raises an **INFO** when the wording changed.
|
||||
That is a prompt, not a verdict — it reports only *that* the claim moved, never whether the new
|
||||
claim is true, because a bash script can verify an entry is internally consistent and nothing more.
|
||||
Answering it is this flow's job: if a retrofit strengthens or otherwise changes the wording of a
|
||||
provenance claim, re-read the upstream research doc first and confirm the stronger wording is
|
||||
actually still true before committing it.
|
||||
|
||||
## Versioning a retrofitted skill
|
||||
|
||||
`SKILL.md` Step 4 says to bump the **patch** version on improve, which presumes there is a version
|
||||
to bump. A pre-ADR-0020 skill often carries none — `metadata.version` only became mandatory under
|
||||
ADR-0022, and this flow is exactly where those skills surface.
|
||||
|
||||
A skill with no `metadata.version` is **seeded at `"1.0.0"`, not bumped**. `"0.1.0"` is reserved
|
||||
for a skill created new by the create flow: it means "created and never yet revised", which
|
||||
understates a skill that has been through retrofit and audit passes without tracking a version.
|
||||
Add the field in this retrofit — the `skill-frontmatter` pre-commit hook blocks the commit without
|
||||
it.
|
||||
|
||||
## Worked example — a description retrofit
|
||||
|
||||
`gitea-issues` before, 827 characters, the single most common shape in the corpus:
|
||||
|
||||
```text
|
||||
Use when reading or writing Gitea issues: listing repo issues, getting a single issue's details/
|
||||
comments/labels, creating an issue, updating its state, adding or editing comments, applying
|
||||
labels via issue_write, or searching issues/PRs across repositories. Triggers on "create an
|
||||
issue", "what issues are open", "get issue #N", "close issue #N", "comment on issue #N", "search
|
||||
issues for X" — even when the user doesn't say "Gitea" explicitly. Composes gitea-labels-
|
||||
milestones for all label inference/resolution and milestone lookup — do not use this skill to
|
||||
manage label or milestone definitions themselves (create/edit/delete a label, create/close a
|
||||
milestone), that's gitea-labels-milestones directly. Do not use for pull requests (use gitea-prs)
|
||||
or for local git branch/commit work (use gitea-branches or git-branches).
|
||||
```
|
||||
|
||||
After, the 290 characters that shipped:
|
||||
|
||||
```text
|
||||
Use when reading or writing Gitea issues — "create an issue", "what issues are open", "close
|
||||
issue #N", "comment on issue #N", "search issues for X" — even when the user does not say
|
||||
"Gitea". Not pull requests -> `gitea-prs`. Not label or milestone definitions ->
|
||||
`gitea-labels-milestones`.
|
||||
```
|
||||
|
||||
The retrofit kept the quoted-phrasing register and dropped the verb list, not the other way round.
|
||||
Either register is admissible — what is banned is carrying both. Choose whichever routes better
|
||||
for the skill in hand; here the quoted user phrasings do, because they are how people actually ask.
|
||||
|
||||
What came out, and why:
|
||||
|
||||
| Removed | Why |
|
||||
|---|---|
|
||||
| The second trigger register — `Triggers on "create an issue", "what issues are open", …` | The same triggers restated as quoted user phrasings. Two registers of one trigger list is a FAIL, not a suggestion. |
|
||||
| `applying labels via issue_write` | Implementation detail. The router does not choose a skill by which MCP call it makes. |
|
||||
| `Composes gitea-labels-milestones for all label inference/resolution and milestone lookup` | A composition note. It changes no routing decision and belongs in `README.md`. |
|
||||
| The parenthetical `(create/edit/delete a label, create/close a milestone)` | Capability enumeration inside a boundary clause. The boundary needs the target, not its feature list. |
|
||||
| The `gitea-branches` / `git-branches` boundary | Dropped entirely. Neither was ever going to win an issue request, so the clause defended against nothing — an invented boundary costs characters and buys no routing accuracy. |
|
||||
| `Do not use for pull requests (use gitea-prs)` prose form | Kept, but rewritten as `Not pull requests -> \`gitea-prs\`.` The rewrite buys characters, one uniform shape for the router, **and** a stricter check: an unresolved arrow target is a blocking ERROR, while an unresolved prose target is only a SUGGESTION unless another target in the same sentence resolves. The prose form does not dangle as loudly. |
|
||||
|
||||
What stayed: one trigger clause, one capability clause, the indirect trigger (genuinely warranted
|
||||
here — people say "create an issue", not "create a Gitea issue"), and the boundary clauses.
|
||||
|
||||
## Two rules the gates enforce but the prose does not spell out
|
||||
|
||||
**Boundary clauses may be plural.** Write one per genuine near-miss — the example above carries
|
||||
two, because two different skills could each steal activations. "A boundary clause" in the
|
||||
contract means *at least one*, not *exactly one*. What is banned is a boundary clause invented for
|
||||
a skill that was never going to compete, not a second real one.
|
||||
|
||||
**Never let a hyphenated routing target wrap across lines in a folded `>` scalar.** YAML folding
|
||||
replaces the newline with a space, so `gitea-labels-` at the end of one line and `milestones` at
|
||||
the start of the next fold into `gitea-labels- milestones`. The gate then reads the target as
|
||||
`gitea-labels`, finds no such skill, and reports a dangling boundary target. This is not
|
||||
hypothetical — it is how `gitea-labels-milestones` broke (issue #100). It is fixed: the corpus
|
||||
carries no dangling target today, and the repo's test suite pins that set as empty, so a
|
||||
reintroduction fails the suite rather than joining a backlog. Reflow the line so the whole name
|
||||
sits on one of them. The same applies to any backticked skill or agent name in a description.
|
||||
@@ -34,7 +34,7 @@ source_keys:
|
||||
- **URL:** https://agentskills.io/skill-creation/best-practices.md
|
||||
- **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md
|
||||
- **Description:** Best practices for skill creators — starting from real expertise, spending context wisely, calibrating control, instruction patterns (gotchas, templates, checklists, validation loops)
|
||||
- **Contributing files:** SKILL.md, references/create.md, references/improve.md, references/contract.md, references/retrofit.md
|
||||
- **Contributing files:** SKILL.md, references/create.md, references/improve.md, references/contract.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## agentskills-optimizing-descriptions
|
||||
@@ -42,7 +42,7 @@ source_keys:
|
||||
- **URL:** https://agentskills.io/skill-creation/optimizing-descriptions.md
|
||||
- **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md
|
||||
- **Description:** How to systematically test and improve skill descriptions for triggering accuracy — eval queries, trigger rate testing, train/validation splits, optimization loop
|
||||
- **Contributing files:** SKILL.md, references/improve.md, references/contract.md, references/retrofit.md
|
||||
- **Contributing files:** SKILL.md, references/improve.md, references/contract.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## agentskills-evaluating-skills
|
||||
|
||||
@@ -165,7 +165,6 @@ cp -r "$TEMPLATES_DIR" "$TARGET"
|
||||
|
||||
# Set skill name in templates
|
||||
sed -i "s/SKILL_NAME/$SKILL_NAME/g" "$TARGET/SKILL.md"
|
||||
sed -i "s/SKILL_NAME/$SKILL_NAME/g" "$TARGET/README.md"
|
||||
sed -i "s/SKILL_NAME/$SKILL_NAME/g" "$TARGET/tests/README.md"
|
||||
|
||||
if [[ "$MODE" == "package" ]]; then
|
||||
|
||||
@@ -34,11 +34,6 @@ teardown() {
|
||||
assert [ -f "$DEST/my-tool/SKILL.md" ]
|
||||
}
|
||||
|
||||
@test "scaffold contains README.md" {
|
||||
bash "$SCRIPT" my-tool "$DEST"
|
||||
assert [ -f "$DEST/my-tool/README.md" ]
|
||||
}
|
||||
|
||||
@test "scaffold contains scripts/, references/, assets/, tests/ directories" {
|
||||
bash "$SCRIPT" my-tool "$DEST"
|
||||
assert [ -d "$DEST/my-tool/scripts" ]
|
||||
@@ -53,12 +48,6 @@ teardown() {
|
||||
assert_success
|
||||
}
|
||||
|
||||
@test "substitutes skill name in README.md" {
|
||||
bash "$SCRIPT" my-tool "$DEST"
|
||||
run grep "my-tool" "$DEST/my-tool/README.md"
|
||||
assert_success
|
||||
}
|
||||
|
||||
@test "substitutes skill name in tests/README.md" {
|
||||
bash "$SCRIPT" my-tool "$DEST"
|
||||
run grep "my-tool" "$DEST/my-tool/tests/README.md"
|
||||
|
||||
@@ -1,79 +0,0 @@
|
||||
# agent-audit
|
||||
|
||||
Audits an agent definition for correctness and quality against the Claude Code and Copilot agent
|
||||
references and the house context-budget contract (ADR-0020) — a single vendor-neutral file at
|
||||
plugin/APM scope, or a Claude Code and Copilot file pair at project/user scope.
|
||||
|
||||
## What it does
|
||||
|
||||
1. Runs `scripts/validate.sh` and `scripts/validate-provenance.sh` for structural and provenance
|
||||
checks, plus `scripts/vale-wrap.sh` — a Vale prefilter that deterministically flags
|
||||
non-imperative description openers, composition and architecture notes, vague wording, padding
|
||||
phrases, "There is/are" sentence openers, and CC-specific "Use proactively" phrasing in a
|
||||
Copilot or vendor-neutral description
|
||||
2. Reads the agent file, and its counterpart when one exists, then loads the contract for its scope
|
||||
3. Applies qualitative checks across description, body, delegation and comment discipline, loading
|
||||
one rubric from `references/` per group
|
||||
4. Outputs a compact findings report — findings only, grouped by dimension, each with Why and Fix —
|
||||
and a result block with handoff to `agent-author`
|
||||
|
||||
Two things follow from ADR-0020 and are easy to get backwards. Agents take the **same** description
|
||||
gates a skill takes — 250 characters SUGGESTION, 400 FAIL, since a `name` + `description` is
|
||||
preloaded into every session either way — and **no body word gate at all**, because an agent body
|
||||
becomes the system prompt of a fresh context rather than competing with the caller's live
|
||||
conversation. Body length is judged through the delegation check instead: an agent body that
|
||||
restates a procedure owned by a skill it can invoke is a FAIL, because a plugin-scope agent has no
|
||||
sibling `references/` directory to disclose to and can only delegate.
|
||||
|
||||
At **plugin/APM scope** the audit accepts the single `.apm/agents/<name>.agent.md` file — there is
|
||||
no counterpart, and pair consistency does not apply. `validate.sh` hard-`FAIL`s any frontmatter
|
||||
field outside the vendor-neutral allowlist, since `apm compile` copies frontmatter verbatim to both
|
||||
harnesses and an unsafe field cannot be silently dropped for just one of them. The allowlist lives
|
||||
in the `apm-agent-allowlist` section of `references/field-inventory.md`, is read from there as data
|
||||
by the script, and is deliberately not restated anywhere else in this skill (ADR-0009).
|
||||
|
||||
At **project/user scope** the audit accepts either file in a CC `.md` / Copilot `.agent.md` pair,
|
||||
derives the counterpart automatically, and validates both, including the field-leakage checks in
|
||||
each direction.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/agent-audit
|
||||
```
|
||||
|
||||
Pass the path to either agent file as the argument.
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `SKILL.md` | Skill instructions for agents |
|
||||
| `assets/vale/.vale.ini` | Vale config: scopes `Kyberforge` to `**/agents/*.md`, `Kyberforge`+`KyberforgeCopilot` to `**/*.agent.md` |
|
||||
| `assets/vale/styles/Kyberforge/CompositionNote.yml` | Flags composition and architecture notes in a description ("cross-cutting", "entry point", "composes", "rather than duplicating") that belong in README.md |
|
||||
| `assets/vale/styles/Kyberforge/DescriptionOpener.yml` | Flags descriptions opening with "This..." instead of an imperative "Use when..." |
|
||||
| `assets/vale/styles/Kyberforge/PaddingPhrase.yml` | Flags generic "see references/ for info" pointers instead of specific file references |
|
||||
| `assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml` | Flags sentences opening with "There is/are" instead of naming the subject directly |
|
||||
| `assets/vale/styles/Kyberforge/VagueWording.yml` | Flags vague capability wording ("helps with", "utilize", "assists with", "used for") in descriptions |
|
||||
| `assets/vale/styles/KyberforgeCopilot/ProactivePhrase.yml` | Flags CC-specific "Use proactively" phrasing with no effect in Copilot descriptions |
|
||||
| `references/README.md` | Directory documentation for references/ |
|
||||
| `references/finding-criteria.md` | Every dimension's FAIL and SUGGESTION criteria — the one Step 3 file read on every run; it decides which rubrics below are worth loading |
|
||||
| `references/description-quality.md` | Rubric for the description dimension — why the description is the expensive part, the hand-invoked contract, the three-part shape, indirect triggers, and near-miss exclusions |
|
||||
| `references/body-and-delegation.md` | Rubric for the body, delegation and comment-discipline dimensions — the core test, the delegation FAIL, why agents take no body word gate, and what an agent body is for |
|
||||
| `references/scope-plugin-apm.md` | Scope contract for a single vendor-neutral APM agent file — allowlist, dimension routing, and the dimensions that do not apply |
|
||||
| `references/scope-project-user.md` | Scope contract for a CC / Copilot pair — counterpart derivation, provider field rules, pair consistency |
|
||||
| `references/validation-scripts.md` | Loaded only when a Step 1 script fails or cannot run — scope-detection walk-up, manual fallback checks, known script failures |
|
||||
| `references/field-inventory.md` | Authoritative field lists read as data by `validate.sh`: valid CC and Copilot agent fields, and the vendor-neutral plugin/APM-scope allowlist |
|
||||
| `references/sources.md` | Research provenance for skill content |
|
||||
| `scripts/README.md` | Directory documentation for scripts/ |
|
||||
| `scripts/validate.sh` | Structural validator — required fields, name format, placeholder detection, the ADR-0020 description budget, and the field rules for the detected scope |
|
||||
| `scripts/validate-provenance.sh` | Provenance chain validation against `sources.md` at the package root (plugin/APM scope only) |
|
||||
| `scripts/vale-wrap.sh` | Drop-in `vale` wrapper that works around a frontmatter-description NLP scope limitation |
|
||||
| `tests/README.md` | (source-only) Bats test dependency and run instructions |
|
||||
| `tests/validate.bats` | (source-only) Bats tests for validate.sh |
|
||||
| `tests/validate-provenance.bats` | (source-only) Bats tests for validate-provenance.sh |
|
||||
|
||||
Rows marked **(source-only)** exist in the authoring source (`.apm/skills/agent-audit/`) but are
|
||||
not present in an installed plugin: `scripts/sync-plugin-content.sh` strips
|
||||
`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
|
||||
plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install.
|
||||
@@ -7,7 +7,7 @@ description: >
|
||||
directory -> skill-audit.
|
||||
allowed-tools: Bash Read
|
||||
metadata:
|
||||
version: "1.0.1"
|
||||
version: "1.0.2"
|
||||
category: factory
|
||||
source_keys:
|
||||
- context7-websites-code-claude
|
||||
@@ -34,7 +34,7 @@ bash scripts/validate-provenance.sh <agent-file>
|
||||
bash scripts/vale-wrap.sh <agent-file> [<counterpart-file>]
|
||||
```
|
||||
|
||||
`validate.sh` takes either half of a project/user-scope pair or the single plugin/APM-scope file, detects the provider from the extension and the scope by walking up, then checks required fields, kebab-case `name`, `FILL IN:` placeholders, template HTML comments left in frontmatter, the ADR-0020 description budget (250 chars SUGGESTION, 400 FAIL, measured on the folded YAML value) and the fields that scope permits. Its findings become the `### Structure` dimension — its FAILs and its SUGGESTIONs both — except the ones the Step 2 scope contract re-routes.
|
||||
`validate.sh` takes either half of a project/user-scope pair or the single plugin/APM-scope file, detects the provider from the extension and the scope by walking up, then checks required fields, kebab-case `name`, `FILL IN:` placeholders, template HTML comments left in frontmatter, the description budget (250 chars SUGGESTION, 400 FAIL, measured on the folded YAML value) and the fields that scope permits. Its findings become the `### Structure` dimension — its FAILs and its SUGGESTIONs both — except the ones the Step 2 scope contract re-routes.
|
||||
|
||||
If a validation script fails or cannot run — Bash denied, `python3` or `vale` absent, `references/field-inventory.md` missing — read `references/validation-scripts.md`; what these scripts measure is not reproducible by reading.
|
||||
|
||||
|
||||
@@ -1,20 +0,0 @@
|
||||
---
|
||||
source_keys: []
|
||||
---
|
||||
|
||||
# references/
|
||||
|
||||
Additional documentation agents load on demand.
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `finding-criteria.md` | Every dimension's FAIL and SUGGESTION criteria — the one Step 3 file read on every run; it decides which rubrics below are worth loading. |
|
||||
| `description-quality.md` | Rubric for the description dimension — why the description is the expensive part, the hand-invoked contract, the three-part shape, indirect triggers, and near-miss exclusions. |
|
||||
| `body-and-delegation.md` | Rubric for the body, delegation and comment-discipline dimensions — the core test, the delegation FAIL, why agents take no body word gate, and what an agent body is for. |
|
||||
| `scope-plugin-apm.md` | Contract for a single vendor-neutral `.apm/agents/<name>.agent.md` file — allowlist, dimension routing, and the dimensions that do not apply. |
|
||||
| `scope-project-user.md` | Contract for a Claude Code / Copilot file pair — counterpart derivation, provider field rules, and pair consistency. |
|
||||
| `validation-scripts.md` | Loaded only when a Step 1 script fails or cannot run — scope-detection walk-up, manual fallback checks, and known script failures. |
|
||||
| `field-inventory.md` | Authoritative field lists, read as data by `validate.sh`: valid CC and Copilot agent fields, and the vendor-neutral plugin/APM allowlist. |
|
||||
| `sources.md` | Research provenance records for skill content. Load only when tracing the origin of a specific rule or field constraint. |
|
||||
@@ -10,7 +10,7 @@ source_keys:
|
||||
# Body, Delegation and Comment Discipline Reference
|
||||
|
||||
Upstream source: Claude Code subagent and plugin references, GitHub Copilot custom-agents
|
||||
configuration. House contract: ADR-0020, the context budget.
|
||||
configuration. House contract: the context budget.
|
||||
|
||||
Read this when judging the **body**, **delegation** and **comment-discipline** dimensions.
|
||||
|
||||
@@ -23,8 +23,8 @@ dilutes the signal of what matters.
|
||||
|
||||
## Agents take no body word gate
|
||||
|
||||
ADR-0020 gates a skill body at 600 words SUGGESTION / 900 FAIL and deliberately gates an agent body
|
||||
at nothing. The two are not the same construct: a skill body is loaded into the caller's live
|
||||
A skill body is gated at 600 words SUGGESTION / 900 FAIL; an agent body is deliberately gated at
|
||||
nothing. The two are not the same construct: a skill body is loaded into the caller's live
|
||||
context and competes with the conversation already there, while an agent body *becomes* the system
|
||||
prompt of a fresh context that has nothing else in it. The rationale for the 900-word ceiling does
|
||||
not transfer, so:
|
||||
|
||||
@@ -9,7 +9,7 @@ source_keys:
|
||||
# Agent Description Quality Reference
|
||||
|
||||
Upstream source: Claude Code subagent reference, GitHub Copilot custom-agents configuration.
|
||||
House contract: ADR-0020, the context budget. The house contract is narrower than either
|
||||
House contract: the context budget. The house contract is narrower than either
|
||||
platform's schema rather than a reinterpretation of it: where both speak, both must be satisfied.
|
||||
|
||||
## Why the description is the expensive part
|
||||
|
||||
@@ -90,8 +90,8 @@ Flag as SUGGESTION if:
|
||||
- A rationale is missing from a rule the agent is expected to enforce — present but unexplained
|
||||
- Comments are useful but verbose enough to bury the field they annotate
|
||||
|
||||
**Never report an agent body as too long on a word count.** ADR-0020 gates a skill body at
|
||||
600/900 words and deliberately gates an agent body at nothing, because an agent body *becomes* the
|
||||
**Never report an agent body as too long on a word count.** A skill body is gated at 600/900 words;
|
||||
an agent body is deliberately gated at nothing, because an agent body *becomes* the
|
||||
system prompt of a fresh context rather than competing with a live conversation. No number exists
|
||||
to cite. The one length signal that applies is the Copilot runtime's 30,000-character body limit,
|
||||
which `validate.sh` already reports as a SUGGESTION. Length is judged through the delegation FAIL
|
||||
|
||||
@@ -1,58 +0,0 @@
|
||||
# agent-author
|
||||
|
||||
Creates and improves agent definition files for Claude Code and GitHub Copilot CLI.
|
||||
|
||||
## What it does
|
||||
|
||||
Scaffolds and fills in agent definition files at plugin/APM, project, or user scope. Project and user scope always generate a Claude Code + Copilot CLI file pair (`.md` + `.agent.md`) in one pass. Plugin/APM scope generates a single vendor-neutral `.apm/agents/<name>.agent.md` file instead — no separate Claude Code / Copilot split, since `apm compile` has no per-target field integrator (see ADR-0016). Also applies improvement signals — grill output, inline feedback, session context — to existing agent files. Bumps the version after every change: the resolved package's `apm.yml` at plugin/APM scope (minor for new agents, patch for improvements); project/user scope has no manifest to bump.
|
||||
|
||||
## Before you start
|
||||
|
||||
Have ready: the agent's name (kebab-case), the root directory (plugin root, project root, or `~`), a one-sentence purpose, and the triggering condition (when should the runtime delegate to this agent?).
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/agent-author
|
||||
```
|
||||
|
||||
**Manual scaffold (human workflow):**
|
||||
```bash
|
||||
bash scripts/new-agent.sh <agent-name> <root>
|
||||
|
||||
# Examples:
|
||||
bash scripts/new-agent.sh code-reviewer packages/my-package/ # plugin/APM scope if packages/my-package/apm.yml has a type: field
|
||||
bash scripts/new-agent.sh deploy-assistant .
|
||||
bash scripts/new-agent.sh security-reviewer ~
|
||||
```
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `SKILL.md` | Skill instructions for agents — gotchas, the create/improve dispatch table, the scope dispatch table, the shared gates, and validation/close |
|
||||
| `scripts/new-agent.sh` | Scaffolds agent definition file(s) from templates — a single `.apm/agents/<name>.agent.md` at plugin/APM scope, or a Claude Code + Copilot CLI pair at project/user scope |
|
||||
| `references/create.md` | Create flow: prerequisites, scaffold and scope walk-up, what to fill in, package-root `sources.md` |
|
||||
| `references/improve.md` | Improve flow: signal verification, root-cause grouping, generalizing, delegation over growth, ADR-0020 retrofit |
|
||||
| `references/contract.md` | Description and body contract: three-part description shape, 250/400 tiers, delegation rule in place of a body word gate, invocation axis |
|
||||
| `references/plugin-scope.md` | Plugin/APM scope field rules for the single vendor-neutral file, plus its pre-audit checklist |
|
||||
| `references/project-user-scope.md` | Project/user scope field rules for the Claude Code + Copilot pair, both Copilot formats, plus its pre-audit checklist |
|
||||
| `references/deployment-modes.md` | Scope hierarchy and precedence, scoped identifiers, cache isolation, path conventions |
|
||||
| `references/scripts.md` | Conventions for new-agent.sh and the templates it copies: contract, template variables, file placement, error messages |
|
||||
| `references/sources.md` | Research provenance — sources that informed this skill |
|
||||
| `assets/templates/claude-code.md` | Annotated Claude Code agent definition template (project/user scope) |
|
||||
| `assets/templates/copilot.agent.md.template` | Annotated Copilot CLI agent definition template (project/user scope) |
|
||||
| `assets/templates/apm-agent.md` | Annotated vendor-neutral APM agent definition template (plugin/APM scope) |
|
||||
| `tests/new-agent.bats` | (source-only) bats tests for `scripts/new-agent.sh` |
|
||||
| `assets/README.md` | Directory meta-documentation for assets/ |
|
||||
| `references/README.md` | Directory meta-documentation for references/ |
|
||||
| `scripts/README.md` | Directory meta-documentation for scripts/ |
|
||||
| `tests/README.md` | (source-only) bats dependency instructions and run command |
|
||||
|
||||
Rows marked **(source-only)** exist in the authoring source (`.apm/skills/agent-author/`) but are
|
||||
not present in an installed plugin: `scripts/sync-plugin-content.sh` strips
|
||||
`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
|
||||
plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install. The
|
||||
`assets/templates/` rows above are unaffected — the exclusion is depth-scoped to
|
||||
`<category>/<name>/tests`, so template trees that themselves contain a `tests/` directory ship
|
||||
intact.
|
||||
@@ -6,7 +6,7 @@ description: >
|
||||
Not read-only review -> `agent-audit`. Not skills -> `skill-author`.
|
||||
allowed-tools: Bash Read Write Edit
|
||||
metadata:
|
||||
version: "1.0.1"
|
||||
version: "1.0.2"
|
||||
category: factory
|
||||
source_keys:
|
||||
- context7-websites-code-claude
|
||||
|
||||
@@ -1,55 +0,0 @@
|
||||
---
|
||||
source_keys: []
|
||||
---
|
||||
|
||||
# references/
|
||||
|
||||
## create.md
|
||||
|
||||
The create flow, loaded from SKILL.md Step 1 when no agent file exists at the target path.
|
||||
Covers: prerequisites, the scaffold script and its scope walk-up, what to fill in at every scope,
|
||||
and populating or deleting the package-root `sources.md`.
|
||||
|
||||
## improve.md
|
||||
|
||||
The improve flow, loaded from SKILL.md Step 1 when a file exists and at least one improvement
|
||||
signal is present. Covers: signal verification, partial-pair recovery, root-cause grouping,
|
||||
generalizing rather than patching, delegation over growth, and the ADR-0020 retrofit rule.
|
||||
|
||||
## contract.md
|
||||
|
||||
The description and body contract, loaded from SKILL.md Step 3 before any description is written
|
||||
or any body restructured. Covers: the three-part description shape, banned description content,
|
||||
boundary-target resolution, the 250/400 length tiers, the body role-instruction pattern, the
|
||||
delegation rule that replaces a body word gate, and the invocation axis.
|
||||
|
||||
## plugin-scope.md
|
||||
|
||||
Field rules and the pre-audit checklist for the single vendor-neutral `.apm/agents/<name>.agent.md`
|
||||
file. Loaded from SKILL.md Step 2 when the scaffold resolves plugin/APM scope.
|
||||
|
||||
## project-user-scope.md
|
||||
|
||||
Field rules and the pre-audit checklist for the Claude Code `.md` + Copilot `.agent.md` pair,
|
||||
including the two distinct Copilot formats. Loaded from SKILL.md Step 2 when the scaffold resolves
|
||||
project or user scope.
|
||||
|
||||
## deployment-modes.md
|
||||
|
||||
Scope hierarchy and precedence, scoped identifiers for plugin subdirectory agents, cache isolation
|
||||
behaviour, and Copilot CLI path conventions. Loaded from SKILL.md Step 2 when precedence, paths or
|
||||
cache isolation matter to the run.
|
||||
|
||||
## scripts.md
|
||||
|
||||
Conventions for the `new-agent.sh` scaffold script, the templates it copies, and any future script
|
||||
in this skill. Loaded from `create.md` Step 1 when the script or a template has to change. Covers:
|
||||
the no-interactive-prompts rule, structured output, idempotency, template variables, file
|
||||
placement, error messages, and the no-restated-field-roster rule that `tests/new-agent.bats`
|
||||
enforces.
|
||||
|
||||
## sources.md
|
||||
|
||||
Research provenance record for this skill. Lists the upstream research sources
|
||||
(claude-code-plugins and github-copilot-plugins research docs) that informed SKILL.md and the
|
||||
reference files. Used by `skill-audit` to validate the provenance chain.
|
||||
@@ -6,7 +6,7 @@ source_keys:
|
||||
|
||||
# The agent description and body contract
|
||||
|
||||
House contract, set by ADR-0020. The counts and the boundary targets are enforced by
|
||||
House contract. The counts and the boundary targets are enforced by
|
||||
`agent-audit`'s `scripts/validate.sh`; the prose patterns by the Vale styles it bundles; the
|
||||
judgment calls by its reference files.
|
||||
|
||||
@@ -40,9 +40,8 @@ Banned from a description; move it to the body or to `README.md`:
|
||||
- Restating the same trigger twice in two registers — a verb list, then the same verbs re-quoted
|
||||
as user phrasings. This is a FAIL, not a suggestion.
|
||||
|
||||
**Do not open with an action verb.** "Reviews…", "Analyzes…", "Generates…" was the old house rule
|
||||
and ADR-0020 deleted it: the opener is `Use when`, matching every skill in this corpus, so one
|
||||
router reads one shape.
|
||||
**Do not open with an action verb.** The opener is `Use when`, matching every skill in this corpus,
|
||||
so one router reads one shape.
|
||||
|
||||
**"Use proactively" is Claude Code-only, and conditional even there.** The phrase steers the
|
||||
Claude Code runtime to offer an agent unprompted and does nothing anywhere else, so where it may
|
||||
|
||||
@@ -66,9 +66,10 @@ answer is no.
|
||||
all caps (ALWAYS/NEVER) is usually better reframed as why the behaviour matters, so the agent can
|
||||
apply judgment at the edges.
|
||||
|
||||
**Retrofit before extending.** Any agent predating ADR-0020 has to meet the description contract
|
||||
before any other edit lands — the gates are hot and carry no baseline file, so a one-line fix to a
|
||||
non-compliant agent cannot be committed until its description meets `references/contract.md`.
|
||||
**Retrofit before extending.** Any agent whose description does not meet the contract has to be
|
||||
brought into compliance before any other edit lands — the gates are hot and carry no baseline file,
|
||||
so a one-line fix to a non-compliant agent cannot be committed until its description meets
|
||||
`references/contract.md`.
|
||||
Treat that retrofit as part of the same change, not a follow-up.
|
||||
|
||||
**Re-check the scope rules.** Read the reference for the resolved scope (`SKILL.md` Step 2) and
|
||||
|
||||
@@ -1,22 +0,0 @@
|
||||
# apm-install
|
||||
|
||||
Installs and configures the `apm` (Agent Package Manager) CLI and the agent runtimes it manages.
|
||||
|
||||
## What it does
|
||||
|
||||
Covers the two provisioning steps for working with apm: installing the `apm` binary itself (quick-install script, pinned version, air-gapped mirror, or pip/pipx), and installing/managing an agent runtime apm drives (`apm runtime setup copilot|codex|gemini|llm`, listing installed runtimes, checking which one `apm run` defaults to).
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/apm-install
|
||||
```
|
||||
|
||||
Once `apm` and a runtime are in place, use `apm-workflow` for authoring `apm.yml`, scaffolding packages/marketplaces, compiling, packing, publishing, and auditing.
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `SKILL.md` | Skill instructions for agents |
|
||||
| `references/sources.md` | Provenance chain — research sources that informed this skill |
|
||||
@@ -1,33 +0,0 @@
|
||||
# apm-workflow
|
||||
|
||||
Authors, scaffolds, compiles, and audits apm packages and marketplaces.
|
||||
|
||||
## What it does
|
||||
|
||||
Covers the apm.yml lifecycle a session moves through repeatedly: configuring/scaffolding a package manifest, resolving/fetching its declared dependencies, building or registering a marketplace, compiling/packing/publishing a distributable, and validating integrity via apm audit. Dispatches on the resolved flow to one of five reference files; each carries that flow's traps and names a sibling file where one flow genuinely depends on another's detail.
|
||||
|
||||
## Before you start
|
||||
|
||||
Requires the `apm` binary and (for runtime-driven scripts) an agent runtime already installed — use `apm-install` first if either is missing.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/apm-workflow configure
|
||||
/apm-workflow install
|
||||
/apm-workflow marketplace
|
||||
/apm-workflow compile
|
||||
/apm-workflow audit
|
||||
```
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `SKILL.md` | Dispatch table and the three gotchas common to every branch (MCP secret indirection, the `experimental enable registries` precondition, the unchecked `type:` field) |
|
||||
| `references/configure.md` | apm.yml schema, apm plugin init, dependency forms, MCP secrets, `includes:`, registries; `type:` and `experimental enable registries` traps |
|
||||
| `references/install.md` | apm install, apm install [PACKAGE_REF], --update, --target agent-skills |
|
||||
| `references/marketplace.md` | Building/registering a marketplace, `marketplace add` vs `package add`, package registration, versioning, Claude Code reserved-name/publish-confirm gotchas |
|
||||
| `references/compile.md` | apm compile / pack / publish / run, claude plugin validate agents/ gotcha |
|
||||
| `references/audit.md` | apm audit vs apm audit --ci (they check different things), apm marketplace check, CI wiring, frozen installs, claude plugin validate terminal check |
|
||||
| `references/sources.md` | Provenance chain — research sources that informed this skill |
|
||||
@@ -1,40 +0,0 @@
|
||||
# forge
|
||||
|
||||
Guided entry point for building or improving something in any plugin of this repo when the target artifact type isn't decided yet.
|
||||
|
||||
## What it does
|
||||
|
||||
Grills the user's intent via `grill-with-docs` (inline, interactive) against this repo's `CONTEXT.md` and `docs/adr/`, classifies the target artifact type (skill, agent/subagent definition, plugin, or marketplace entry), announces the classification, then routes to the matching author skill — chaining more than one, in dependency order, if the intent spans multiple artifact types.
|
||||
|
||||
Author-skill invocation defaults to a fork subagent (inherits the grilled-intent context) and falls back to inline when forking isn't possible or the routed flow needs live user interaction (clarifying questions, a HITL gate). After a `skill-author` or `agent-author` route finishes — each already closes out with its own inline audit — forge spins up a separate clean-context subagent to independently re-run the matching audit skill (`skill-audit` / `agent-audit`) as a distinct check on the finished artifact, not a duplicate of the inline one. If that clean audit turns up any unresolved finding, forge loops — re-invoke the author skill to resolve it, re-run the clean audit — until the clean audit comes back with nothing unresolved. `apm-workflow` routes (plugin, marketplace entry) get no recheck: they have no audit counterpart, and no automatic terminal check either — `apm audit` is a separate `apm-workflow` action, not a closing step of the configure or marketplace flow — so forge verifies those routes by reading the written manifest back against the grilled intent.
|
||||
|
||||
## Before you start
|
||||
|
||||
Have a rough idea of what you want to build or change. forge doesn't require you to already know whether it's a skill, agent, plugin, or marketplace entry — that classification is its job.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/forge
|
||||
```
|
||||
|
||||
Skip forge and call the target skill directly (`/skill-author`, `/agent-author`, `/apm-workflow`) when you already know the artifact type.
|
||||
|
||||
## Files
|
||||
|
||||
| File | Loaded when |
|
||||
|------|-------------|
|
||||
| `SKILL.md` | Always — Gotchas, the grill step, the classification dispatch table, and the gates common to every route |
|
||||
| `references/author-routes.md` | The intent classifies as a skill or an agent/subagent definition — fork-vs-inline judgment and the two-tier verification loop |
|
||||
| `references/apm-routes.md` | The intent classifies as a plugin or a marketplace entry — always-inline invocation, why these routes get no clean-context recheck, and the manual read-back that stands in for one |
|
||||
| `references/version-bump.md` | A finished route left the owning package's version unbumped — walk-up rule and the clean-context bump brief |
|
||||
| `references/sources.md` | Never loaded at runtime — provenance chain for the research sources that informed this skill |
|
||||
|
||||
## Routes to
|
||||
|
||||
| Artifact type | Skill |
|
||||
|---|---|
|
||||
| Skill | `skill-author` |
|
||||
| Agent / subagent definition | `agent-author` |
|
||||
| Plugin | `apm-workflow` (configure) |
|
||||
| Marketplace entry | `apm-workflow` (marketplace) |
|
||||
@@ -8,7 +8,7 @@ description: >
|
||||
already named — invoke `skill-author`, `agent-author` or `apm-workflow`
|
||||
directly.
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
version: "1.0.1"
|
||||
category: factory
|
||||
source_keys:
|
||||
- claude-code-subagents-docs
|
||||
|
||||
@@ -28,7 +28,7 @@
|
||||
|
||||
- **URL:** https://agentskills.io/specification.md
|
||||
- **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md
|
||||
- **Description:** Complete SKILL.md format specification — confirms `assets/`, `references/`, and `scripts/` are warranted only by the bulk/reusability of supporting content (large reference material, executable code, templates), not by a skill's category, and forge's per-route procedures are that kind of supporting content — so the spec permits the `references/` split here but does not require it. The warrant is a house decision: ADR-0020's rule that dispatch is mandatory at two or more mutually exclusive flows, which forge's four-row table is. `references/sources.md` likewise exists for this repo's own provenance-chain convention (see `CONTEXT.md`), not because the spec requires it.
|
||||
- **Description:** Complete SKILL.md format specification — confirms `assets/`, `references/`, and `scripts/` are warranted only by the bulk/reusability of supporting content (large reference material, executable code, templates), not by a skill's category, and forge's per-route procedures are that kind of supporting content — so the spec permits the `references/` split here but does not require it. The warrant is a house decision: dispatch is mandatory at two or more mutually exclusive flows, which forge's four-row table is. `references/sources.md` likewise exists for this repo's own provenance-chain convention (see `CONTEXT.md`), not because the spec requires it.
|
||||
- **Contributing files:** SKILL.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
|
||||
@@ -1,53 +0,0 @@
|
||||
# skill-audit
|
||||
|
||||
Audit a skill directory against the agentskills.io specification and the house context-budget contract (ADR-0020). Runs structural validation then a qualitative review across description quality, body discipline, patterns, formatting, file structure, scripts, and internal consistency, plus a provenance chain check.
|
||||
|
||||
## What it does
|
||||
|
||||
1. Runs `scripts/validate.sh` and `scripts/validate-provenance.sh` for structural and provenance checks, plus `scripts/vale-wrap.sh` — a Vale prefilter that deterministically flags non-imperative description openers, composition and architecture notes, vague wording, padding phrases, and "There is/are" sentence openers
|
||||
2. Reads all files in the skill directory
|
||||
3. Applies qualitative checks across five dimension groups — always loading `references/finding-criteria.md`, then one rubric from `references/` per group the criteria put in play
|
||||
4. Outputs a compact findings report — findings only, grouped by dimension, each with Why and Fix — and a result block with handoff to `skill-author`
|
||||
|
||||
`validate.sh` enforces two independent length families that must not be conflated: the agentskills.io spec conformance ceilings (500 lines, 2,770 words, both counting the whole file) and the ADR-0020 context budget (250/400 description characters, 600/900 body-only words).
|
||||
|
||||
Alongside those it runs shape checks that are not length measurements at all. Three are FAILs: every routing target named in the description — in the compressed `Not <thing> -> <name>` arrow **and** in the prose form — must resolve to a real skill or agent; every `references/<file>.md` the body names must exist on disk; and `metadata.version` must be present and three-part semver (ADR-0022). That last one is FAIL rather than SUGGESTION because the `skill-frontmatter` pre-commit hook rejects the file without it — an audit grading it lower would report ready-to-ship on a file the commit gate refuses. Three are SUGGESTIONs: a missing boundary clause, a Gotchas section over five entries, and a Gotchas section over 25% of the body. The resolution universe for boundary targets is derived by walking up from the audited `SKILL.md` — the authoring root above it, its own apm package, and that package's declared `apm.yml` dependencies — so a fresh clone and a machine that has run `apm install` return the same verdict. When no universe can be determined the check prints `INFO ... DID NOT RUN` and does not silently pass.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/skill-audit
|
||||
```
|
||||
|
||||
Provide the path to the skill directory to audit when invoking.
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `SKILL.md` | Skill instructions for agents |
|
||||
| `scripts/validate.sh` | Structural validator — checks name format, name matches directory, description presence and length, `metadata.version` presence and semver shape (ADR-0022), body-only word count, line and whole-file word ceilings, boundary-clause presence, boundary-target resolution, `references/` pointer existence, Gotchas entry count and body share, placeholder detection, script executable bit, and interactive-prompt detection |
|
||||
| `scripts/validate-provenance.sh` | Provenance validator — checks sources.md completeness, source_keys/slug consistency, Contributing files existence, bidirectional linkage, Research doc: fields, upstream research doc alignment, and (check 9, INFO only) whether a slug's `Description` or `Contributing files` text has changed since a base ref — `--base-ref=<ref>` or `VALIDATE_PROVENANCE_BASE_REF`, defaulting to the merge base with `origin/main` |
|
||||
| `scripts/vale-wrap.sh` | Vale prefilter wrapper — runs the bundled `Kyberforge` Vale styles against SKILL.md and reports alerts as deterministic FAILs ahead of Step 3's qualitative review |
|
||||
| `assets/vale/.vale.ini` | Vale configuration — points Vale at the bundled `Kyberforge` style path, self-located relative to `vale-wrap.sh` |
|
||||
| `assets/vale/styles/Kyberforge/CompositionNote.yml` | Vale rule — flags composition and architecture notes in a description (e.g. "cross-cutting", "entry point", "rather than duplicating") |
|
||||
| `assets/vale/styles/Kyberforge/DescriptionOpener.yml` | Vale rule — flags non-imperative "This..." description openers |
|
||||
| `assets/vale/styles/Kyberforge/PaddingPhrase.yml` | Vale rule — flags generic "see references/" padding phrasing in conditional references |
|
||||
| `assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml` | Vale rule — flags body sentences starting with "There is"/"There are" |
|
||||
| `assets/vale/styles/Kyberforge/VagueWording.yml` | Vale rule — flags known filler wording (e.g. "helps with", "utilize") |
|
||||
| `references/finding-criteria.md` | Every dimension's FAIL and SUGGESTION criteria — the one Step 3 file loaded on every run; it decides which rubrics below are worth loading |
|
||||
| `references/description-quality.md` | Rubric for the description dimension — why the description is the expensive part, the hand-invoked (`disable-model-invocation`) contract, the three-part shape, when an indirect trigger is warranted, near-miss exclusions, and a before/after pair |
|
||||
| `references/body-discipline.md` | Rubric for the body-discipline dimension — the core test, the 600/900 body-only budget against the 2,770-word whole-file backstop, the mandatory-dispatch rule, and the Gotchas constraints |
|
||||
| `references/patterns.md` | Rubric for the patterns dimension — which instruction construct fits which job, and how each is correctly formed |
|
||||
| `references/file-structure.md` | Rubric for the file-structure and internal-consistency dimensions — permitted directories, cross-plugin path rules and their two structural exemptions, README drift |
|
||||
| `references/formatting-and-scripts.md` | Rubric for the formatting and scripts dimensions — heading and fencing conventions, and the agentic-use criteria for bundled scripts |
|
||||
| `references/validation-scripts.md` | Step 1 troubleshooting — the manual structural fallback when `validate.sh` cannot run, and the script exit codes that are easy to misread (loaded on a script failure, and on any exit-0 run that printed something — `validate-provenance.sh`'s check 9 is INFO-only, so its findings arrive that way) |
|
||||
| `references/sources.md` | Provenance record — agentskills.io sources that informed this skill and which files each contributed to |
|
||||
| `tests/validate.bats` | (source-only) Bats test suite for validate.sh |
|
||||
| `tests/validate-provenance.bats` | (source-only) Bats test suite for validate-provenance.sh |
|
||||
| `tests/README.md` | (source-only) Setup instructions for bats-support and bats-assert test dependencies |
|
||||
|
||||
Rows marked **(source-only)** exist in the authoring source (`.apm/skills/skill-audit/`) but are
|
||||
not present in an installed plugin: `scripts/sync-plugin-content.sh` strips
|
||||
`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
|
||||
plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install.
|
||||
@@ -7,7 +7,7 @@ description: >
|
||||
skill-author.
|
||||
allowed-tools: Bash Read
|
||||
metadata:
|
||||
version: "1.0.1"
|
||||
version: "1.0.2"
|
||||
category: factory
|
||||
source_keys:
|
||||
- agentskills-home
|
||||
@@ -50,7 +50,7 @@ Read `references/validation-scripts.md` when any of the three cannot run or exit
|
||||
|
||||
## Step 2 — Read the whole skill
|
||||
|
||||
Read `SKILL.md`, `README.md`, and every text file under `scripts/`, `references/`, `assets/` and `tests/`. Skip binaries only — internal-consistency findings need the full picture.
|
||||
Read `SKILL.md` and every text file under `scripts/`, `references/`, `assets/` and `tests/`. Skip binaries only — internal-consistency findings need the full picture.
|
||||
|
||||
## Step 3 — Qualitative audit
|
||||
|
||||
@@ -64,7 +64,7 @@ Read `references/finding-criteria.md` first — every dimension's FAIL and SUGGE
|
||||
| file-structure, internal-consistency | `references/file-structure.md` |
|
||||
| formatting, scripts | `references/formatting-and-scripts.md` |
|
||||
|
||||
Each rubric is self-contained and grounded in the agentskills.io specification plus the house context budget (ADR-0020). Cite file and line number for every finding.
|
||||
Each rubric is self-contained and grounded in the agentskills.io specification plus the house context budget. Cite file and line number for every finding.
|
||||
|
||||
## Step 4 — Report
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@ source_keys:
|
||||
# Body Discipline Reference
|
||||
|
||||
Upstream source: agentskills.io — skill-authoring, best-practices.
|
||||
House contract: ADR-0020, the context budget.
|
||||
House contract: the context budget.
|
||||
|
||||
## The core test
|
||||
|
||||
@@ -31,7 +31,7 @@ Include content the agent lacks:
|
||||
Move to `references/`, behind an explicit "If X, read `references/<file>.md`" trigger — the literal
|
||||
conditional form, never a generic pointer. Write the real filename in the skill under audit; the
|
||||
angle brackets are a placeholder here, and a literal `references/file.md` in a body is an ERROR
|
||||
from the ADR-0020 gate because no such file exists on disk.
|
||||
from the gate because no such file exists on disk.
|
||||
|
||||
**A dispatch table satisfies this requirement on its own.** A table row already pairs a condition
|
||||
with a target, which is exactly what the literal form encodes; restating each row underneath as a
|
||||
@@ -60,7 +60,7 @@ Do not conflate these, and do not report them as one finding.
|
||||
|
||||
| Gate | SUGGESTION | FAIL | Counts |
|
||||
|---|---|---|---|
|
||||
| Body budget (house, ADR-0020) | 600 words | 900 words | the **body only** — everything after the frontmatter's closing `---` |
|
||||
| Body budget (house) | 600 words | 900 words | the **body only** — everything after the frontmatter's closing `---` |
|
||||
| Spec conformance (agentskills.io) | — | 2,770 words / 500 lines | the **whole file**, frontmatter included |
|
||||
|
||||
The 2,770-word ceiling is a token-conformance backstop calibrated to the densest prose in the
|
||||
@@ -134,7 +134,7 @@ Constraints:
|
||||
|
||||
Worked negative example — **`git-commits` v0.1.2 at commit `5e23250`, a fixed pre-retrofit
|
||||
snapshot, not the current file.** The live skill is v0.1.3 and matches none of the citations below;
|
||||
they are quoted as they stood before the ADR-0020 retrofit, and are not to be refreshed against
|
||||
they are quoted as they stood in that snapshot, and are not to be refreshed against
|
||||
`HEAD`. The snapshot is reachable only from a checkout of the authoring repo — an installed plugin
|
||||
cache holds no git history and no such path — so read the citations below as quoted rather than
|
||||
going to look for the file. From a checkout:
|
||||
|
||||
@@ -7,7 +7,7 @@ source_keys:
|
||||
# Description Quality Reference
|
||||
|
||||
Upstream source: agentskills.io — optimizing-descriptions, specification.
|
||||
House contract: ADR-0020, the context budget. The house contract is narrower than the spec
|
||||
House contract: the context budget. The house contract is narrower than the spec
|
||||
rather than a reinterpretation of it: where both speak, both must be satisfied.
|
||||
|
||||
## Why the description is the expensive part
|
||||
|
||||
@@ -19,7 +19,6 @@ knows to look at. Flag any other directory as a FAIL.
|
||||
`test_*.sh`) there are a FAIL — they belong in `tests/`.
|
||||
- No non-spec files at the skill root: no `META.md`, no stray config outside the four directories.
|
||||
- An optional directory that exists must hold real content, not an unfilled placeholder README.
|
||||
- `README.md` is present and describes the skill and its files accurately.
|
||||
|
||||
## Cross-plugin path references
|
||||
|
||||
@@ -41,7 +40,7 @@ Resolve before flagging, twice over:
|
||||
**Referring to another skill's file.** There is one sanctioned spelling, and it is possessive:
|
||||
`skill-audit's references/validation-scripts.md`. Write the skill by name and let the reader
|
||||
resolve it — do not spell the repo path. The full path is the thing this section forbids, and
|
||||
`references/validation-scripts.md` on its own is a hard ERROR from the ADR-0020 gate, which
|
||||
`references/validation-scripts.md` on its own is a hard ERROR from the gate, which
|
||||
requires an unqualified `references/` pointer to exist in the skill's OWN directory. The
|
||||
possessive form is the only spelling both rules accept; the gate recognises it and skips the
|
||||
on-disk check. Flag any other spelling of a cross-skill reference.
|
||||
@@ -59,17 +58,12 @@ Two directories are exempt, and the exemptions are structural rather than discre
|
||||
|
||||
## Internal consistency
|
||||
|
||||
The skill has to agree with itself. Three checks:
|
||||
The skill has to agree with itself. Two checks:
|
||||
|
||||
- `SKILL.md`'s steps match what the scripts actually do — the arguments, the exit codes, and the
|
||||
output shape it tells the agent to expect.
|
||||
- `README.md`'s file table lists every file that exists, with no missing rows and no stale rows for
|
||||
files since deleted.
|
||||
- Placeholder READMEs inside `scripts/`, `references/` and `assets/` say the same thing about each
|
||||
- Placeholder READMEs inside `scripts/`, `tests/` and `assets/` say the same thing about each
|
||||
directory that `SKILL.md` does.
|
||||
|
||||
A stale README row is the most common finding here and the easiest to miss from inside an
|
||||
authoring pass, because the author knows what was intended and reads it into the gap.
|
||||
|
||||
The FAIL and SUGGESTION criteria for this dimension live in `references/finding-criteria.md`,
|
||||
which Step 3 loads on every run.
|
||||
|
||||
@@ -111,13 +111,11 @@ Flag as FAIL if:
|
||||
- A path that resolves outside the skill directory appears outside the two exempt locations, in
|
||||
prose rather than in a fenced example
|
||||
- `tests/` exists but `tests/README.md` is missing or does not document its repo-level dependency
|
||||
- `README.md` is absent, or its file table has a missing or stale row
|
||||
- `SKILL.md` describes a script invocation the script does not accept
|
||||
|
||||
Flag as SUGGESTION if:
|
||||
|
||||
- An optional directory exists but holds only a placeholder README
|
||||
- `README.md` is accurate but describes a file's purpose more thinly than `SKILL.md` does
|
||||
|
||||
## formatting and scripts — `references/formatting-and-scripts.md`
|
||||
|
||||
|
||||
@@ -40,7 +40,7 @@ If the API returns a non-200 status, read `references/api-errors.md`.
|
||||
```
|
||||
|
||||
That block is fenced because the filename in it is illustrative — an unfenced `references/` pointer
|
||||
in a `SKILL.md` body must resolve on disk or the ADR-0020 gate reports a hard ERROR. The generic
|
||||
in a `SKILL.md` body must resolve on disk or the gate reports a hard ERROR. The generic
|
||||
form — pointing at the directory and hoping — defeats
|
||||
progressive disclosure, because the agent either loads everything or loads nothing.
|
||||
`Kyberforge.PaddingPhrase` catches the common generic phrasing deterministically; other malformed
|
||||
|
||||
@@ -21,7 +21,7 @@ have checked, and the Step 4 coverage line then names a dimension nothing actual
|
||||
## Manual structural fallback
|
||||
|
||||
`validate.sh` needs `python3` **and** PyYAML, and refuses to start without either — the description
|
||||
value has to be measured after YAML folding is resolved, so skipping the ADR-0020 gates would be a
|
||||
value has to be measured after YAML folding is resolved, so skipping these gates would be a
|
||||
vacuous pass rather than a partial one. The two are checked separately, so the message already names
|
||||
the right one — report it verbatim rather than diagnosing further:
|
||||
|
||||
@@ -40,14 +40,14 @@ by hand and file the results under `### Structure` exactly as the script's outpu
|
||||
session, so a skill without one can never be routed to.
|
||||
- **Description length**, measured on the folded YAML value with newlines collapsed to single
|
||||
spaces — not on the raw block scalar, which counts indentation. 250 characters SUGGESTION, 400
|
||||
FAIL (ADR-0020), 1,024 FAIL (agentskills.io spec).
|
||||
FAIL (house), 1,024 FAIL (agentskills.io spec).
|
||||
- **Body length**, counting everything after the frontmatter's closing `---`. 600 words
|
||||
SUGGESTION, 900 FAIL (ADR-0020).
|
||||
SUGGESTION, 900 FAIL (house).
|
||||
- **Whole-file ceilings**, counting the file including frontmatter: 500 lines FAIL, 2,770 words
|
||||
FAIL (agentskills.io spec). These are a different measurement from the two above — report them
|
||||
as separate findings, never merged.
|
||||
- **A boundary clause is present** — either the prose form (`do not` / `instead` / `rather than` /
|
||||
`not for`) or ADR-0020's compressed `Not <thing> -> <name>` arrow. **SUGGESTION**, not FAIL:
|
||||
`not for`) or the compressed `Not <thing> -> <name>` arrow. **SUGGESTION**, not FAIL:
|
||||
the absence is deterministic, but whether this skill warrants one is the auditor's call.
|
||||
- **Boundary targets resolve** — **FAIL** on a name that resolves to nothing. See the section
|
||||
below; resolving these by hand is the one item on this list with a procedure of its own.
|
||||
|
||||
@@ -1,74 +0,0 @@
|
||||
# skill-author
|
||||
|
||||
Author and refine skills conforming to the [agentskills.io](https://agentskills.io) specification — create new skills from scratch or apply improvement signals to existing ones.
|
||||
|
||||
## What it does
|
||||
|
||||
Routes to one of two flows based on context: if no skill directory exists at the target path, it scaffolds the directory from annotated templates, fills in `SKILL.md` and supporting files, and validates the result. If an existing skill directory and improvement signals are both present, it groups those signals by root cause and applies targeted edits, then re-validates. In both flows, bumps the skill's `metadata.version` — minor for create, patch for improve — which every skill carries (ADR-0022).
|
||||
|
||||
`SKILL.md` itself carries only the dispatch table, the invocation-axis decision, the contract gates and the shared close; each flow lives in its own self-contained reference file, per ADR-0020.
|
||||
|
||||
## The contract it teaches
|
||||
|
||||
Authored skills are held to the ADR-0020 context budget. A description carries a trigger clause, at most one capability clause, and a boundary clause of the form `Not <thing> -> <skill-name>` whose target must resolve to a real skill or agent — 250 characters target, 400 hard ceiling. A body carries the decision procedure only — 600 words target, 900 hard ceiling, counting the body alone, which is a separate measurement from the 2,770-word / 500-line whole-file spec backstop. Skills with two or more mutually exclusive flows must dispatch. `references/contract.md` holds the full rules; `assets/templates/SKILL.md` encodes them as a fill-in skeleton.
|
||||
|
||||
Before a description is written, the skill asks whether the target is model-invoked or hand-invoked. A hand-invoked skill sets `disable-model-invocation: true` and carries one plain human-facing sentence with no trigger list.
|
||||
|
||||
## Before you start
|
||||
|
||||
- Run `/grill-me` to resolve design decisions before creating a new skill
|
||||
- Collect domain research, examples, and constraints
|
||||
- Know the skill name (kebab-case) and destination path
|
||||
|
||||
## Placement
|
||||
|
||||
`scripts/new-skill.sh` resolves the mode automatically by walking up from the given path — see `references/create.md` Step 1 for the full algorithm.
|
||||
|
||||
| Mode | Path | Chosen when |
|
||||
|------|------|-------------|
|
||||
| Standalone | `<path>/<name>/` | No `apm.yml` with a top-level `type:` field is found walking up from `<path>`, before hitting `.git` or the filesystem root |
|
||||
| Package (APM) | `<package-root>/.apm/skills/<name>/` | A type-bearing `apm.yml` is found at or above `<path>` — `<path>` just needs to be somewhere inside the package |
|
||||
|
||||
If the destination resolves inside an APM package, read `references/deployment-modes.md` — self-containment rules apply to `apm compile` output the same way they applied to plugin cache isolation.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/skill-author
|
||||
```
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `README.md` | Human-readable overview of the skill and its files |
|
||||
| `SKILL.md` | Skill instructions for agents |
|
||||
| `scripts/new-skill.sh` | Walks up from the given path to resolve package vs standalone mode, then copies annotated templates to the resolved destination |
|
||||
| `references/create.md` | The create flow end to end — prerequisites, package-intent gate, scaffold, frontmatter, scripts, references, sources (loaded on demand) |
|
||||
| `references/improve.md` | The improve flow end to end — signal verification, root-cause grouping, announcement, edits (loaded on demand) |
|
||||
| `references/contract.md` | The ADR-0020 description and body contract, the Gotchas constraint, the two size gates, body patterns, and org-policy embedding (loaded on demand) |
|
||||
| `references/retrofit.md` | Bringing a pre-ADR-0020 skill into contract — ordered cut procedure, the mutually-exclusive-flows test, reference-file conventions, the collateral checklist, and a worked description retrofit (loaded from the improve flow when a budget is exceeded) |
|
||||
| `references/deployment-modes.md` | APM package vs standalone differences and self-containment/cache-isolation rules (loaded on demand) |
|
||||
| `references/scripts.md` | Package runners, inline dependency patterns, and full script contract (loaded on demand) |
|
||||
| `references/sources.md` | Upstream research sources and which skill files each contributed to |
|
||||
| `assets/templates/SKILL.md` | Annotated SKILL.md template — emits an ADR-0020-compliant description and body skeleton |
|
||||
| `assets/templates/README.md` | Annotated README template for the new skill |
|
||||
| `assets/templates/scripts/README.md` | Placeholder for bundled scripts |
|
||||
| `assets/templates/references/README.md` | Placeholder for reference docs |
|
||||
| `assets/templates/references/sources.md` | Sources provenance template for new skills |
|
||||
| `assets/templates/assets/README.md` | Placeholder for static assets |
|
||||
| `assets/templates/tests/README.md` | Placeholder for test files |
|
||||
| `tests/new-skill.bats` | (source-only) Bats test suite for `scripts/new-skill.sh` |
|
||||
| `tests/README.md` | (source-only) Setup instructions for bats-support and bats-assert test dependencies |
|
||||
|
||||
Rows marked **(source-only)** exist in the authoring source (`.apm/skills/skill-author/`) but are
|
||||
not present in an installed plugin: `scripts/sync-plugin-content.sh` strips
|
||||
`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
|
||||
plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install. The
|
||||
`assets/templates/tests/README.md` row above is **not** source-only — the exclusion is depth-scoped
|
||||
to `<category>/<name>/tests`, so the scaffolding template tree ships intact, which
|
||||
`scripts/new-skill.sh` depends on at runtime.
|
||||
|
||||
## Spec reference
|
||||
|
||||
[agentskills.io specification](https://agentskills.io/specification.md)
|
||||
@@ -6,7 +6,7 @@ description: >
|
||||
Not read-only review -> `skill-audit`. Not agent files -> `agent-author`.
|
||||
allowed-tools: Bash Read Write Edit
|
||||
metadata:
|
||||
version: "1.0.1"
|
||||
version: "1.0.2"
|
||||
category: factory
|
||||
source_keys:
|
||||
- agentskills-home
|
||||
|
||||
@@ -1,51 +0,0 @@
|
||||
# SKILL_NAME
|
||||
|
||||
<!-- FILL IN: One sentence describing what this skill does. -->
|
||||
|
||||
## What it does
|
||||
|
||||
<!-- FILL IN: 2–4 sentences. What task does this skill handle?
|
||||
What does the agent produce or accomplish when it runs? -->
|
||||
|
||||
## Before you start
|
||||
|
||||
<!-- FILL IN: List any prerequisites the user should have ready.
|
||||
Examples: research docs, a grill session, specific input files, credentials.
|
||||
Delete this section if the skill has no meaningful prerequisites. -->
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/SKILL_NAME
|
||||
```
|
||||
|
||||
<!-- FILL IN: Add any required or common arguments.
|
||||
If the skill takes no arguments, delete the code block above and just keep the slash command. -->
|
||||
|
||||
<!-- OPTIONAL: Manual (human) workflow — include if the skill bundles scripts a human can run directly.
|
||||
|
||||
**Manual workflow:**
|
||||
```bash
|
||||
# FILL IN: step-by-step commands
|
||||
```
|
||||
-->
|
||||
|
||||
## Files
|
||||
|
||||
<!-- FILL IN: List each file individually. Remove rows for directories you deleted.
|
||||
Replace the example rows below with your actual files. -->
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `SKILL.md` | Skill instructions for agents |
|
||||
| `scripts/your-script.sh` | FILL IN: what this script does |
|
||||
| `references/your-doc.md` | FILL IN: what this reference covers |
|
||||
| `assets/your-asset.json` | FILL IN: what this asset is |
|
||||
| `tests/your-test.bats` | FILL IN: what this test covers |
|
||||
|
||||
<!-- OPTIONAL: Spec reference — include if this skill implements or follows an external standard.
|
||||
|
||||
## Spec reference
|
||||
|
||||
[FILL IN: Spec name](FILL IN: URL)
|
||||
-->
|
||||
@@ -1,39 +0,0 @@
|
||||
# references/
|
||||
|
||||
Additional documentation agents load on demand. Files here extend SKILL.md
|
||||
without bloating its core context.
|
||||
|
||||
## When to add a reference file
|
||||
|
||||
The SKILL.md body carries the decision procedure only. Everything else lives
|
||||
here: lookup tables, spec restatements, output schemas, templates, example
|
||||
blocks, rationale prose, and anything only one branch reaches.
|
||||
|
||||
Two triggers make a reference file mandatory rather than optional:
|
||||
|
||||
- The body is over its 600-word target (900 is a hard failure), counting the
|
||||
body only — everything after the frontmatter's closing `---`.
|
||||
- The skill has two or more mutually exclusive flows. The body then keeps only
|
||||
a dispatch table plus the gates common to every branch, and each flow gets
|
||||
its own self-contained file here (e.g. `create.md`, `improve.md`).
|
||||
|
||||
## How to reference from SKILL.md
|
||||
|
||||
Load conditionally — tell the agent exactly when to read each file:
|
||||
|
||||
```markdown
|
||||
If the API returns a non-200 status, read `references/api-errors.md`.
|
||||
```
|
||||
|
||||
Avoid generic "see references/ for details" — the agent loads context on
|
||||
demand, so give it a precise trigger condition.
|
||||
|
||||
## File conventions
|
||||
|
||||
- One topic per file — focused files mean less unnecessary context loaded
|
||||
- Kebab-case filenames (e.g. `api-errors.md`, `output-formats.md`)
|
||||
- Keep files under 200 lines where possible
|
||||
|
||||
## If no reference files are needed
|
||||
|
||||
Delete this README and the `references/` directory entirely.
|
||||
@@ -7,7 +7,7 @@ source_keys:
|
||||
|
||||
# The description and body contract
|
||||
|
||||
House contract, set by ADR-0020. Every rule here is enforced by `/skill-audit` —
|
||||
House contract. Every rule here is enforced by `/skill-audit` —
|
||||
`scripts/validate.sh` for the counts and the boundary targets, the bundled Vale styles for the
|
||||
prose patterns, and its reference files for the judgment calls.
|
||||
|
||||
|
||||
@@ -84,7 +84,7 @@ already covers the new skill. Use Read/Edit directly on `apm.yml`; this is not p
|
||||
## 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 ADR-0020 body skeleton and the two frontmatter
|
||||
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.
|
||||
|
||||
@@ -71,23 +71,16 @@ outperforms an exhaustive one.
|
||||
writing a rule in all caps (ALWAYS/NEVER), reframe it: explain why the behavior matters so the
|
||||
agent can apply judgment in edge cases.
|
||||
|
||||
**Retrofit before extending.** Any edit to a skill that predates ADR-0020 has to bring it into the
|
||||
contract first — the gates are hot and carry no baseline file, so a one-line fix to a
|
||||
**Retrofit before extending.** Any edit to a skill that does not meet the contract has to bring it
|
||||
into compliance first — the gates are hot and carry no baseline file, so a one-line fix to a
|
||||
non-compliant skill cannot be committed until the description and body meet
|
||||
`references/contract.md`. Treat that retrofit as part of the same change, not a follow-up.
|
||||
|
||||
If the skill's description exceeds 250 characters, or its body-only word count exceeds 600, read
|
||||
`references/retrofit.md` before editing. It carries the ordered cut procedure, the
|
||||
mutually-exclusive-flows test, the reference-file conventions this flow needs, the collateral
|
||||
checklist for `README.md` and `references/sources.md`, and a worked description retrofit. Do not
|
||||
improvise the cuts — four dry runs invented six to ten different answers to the same questions.
|
||||
|
||||
If a signal points to a script or reference file, edit that file directly rather than adding a
|
||||
workaround in SKILL.md.
|
||||
|
||||
**A skill carrying no `metadata.version` is seeded at `"1.0.0"`, not bumped** — `SKILL.md` Step 4's
|
||||
patch bump presumes a version to bump, and ADR-0022 reserves `"0.1.0"` for a newly created skill.
|
||||
`references/retrofit.md` carries the reasoning.
|
||||
|
||||
**Check for regressions before handing back.** `SKILL.md` Step 4 tells you to resolve every FAIL,
|
||||
which says nothing about a check that passed *before* these edits and no longer does. Compare the
|
||||
|
||||
@@ -1,197 +0,0 @@
|
||||
---
|
||||
source_keys:
|
||||
- agentskills-best-practices
|
||||
- agentskills-optimizing-descriptions
|
||||
---
|
||||
|
||||
# Retrofitting a skill to the ADR-0020 contract
|
||||
|
||||
Read this when `references/improve.md` Step 4 sends you here: the skill you are editing is over
|
||||
the description or body budget and has to come into contract before any other change can be
|
||||
committed. The gates are hot and carry no baseline file, so a one-line fix to a non-compliant
|
||||
skill is blocked until this is done.
|
||||
|
||||
Measure first. Do not guess which gate fired: run `/skill-audit` on the directory and read its
|
||||
`### Structure` dimension, which reports the description characters and the **body-only** word
|
||||
count separately from the whole-file spec backstop. Retrofit against the number that actually
|
||||
fired — a skill can sit a thousand words inside the whole-file backstop while failing the body
|
||||
budget.
|
||||
|
||||
**Validate in place.** Audit the skill's real directory inside its package. Never audit a copy in a
|
||||
scratch directory, and never move a skill out to work on it: the boundary-target universe is built
|
||||
by walking up *from the file being checked*, so a copy with no authoring root above it resolves
|
||||
against nothing and the check declines rather than running —
|
||||
|
||||
```text
|
||||
INFO boundary-target resolution DID NOT RUN — no skill universe could be determined for
|
||||
this path ... Unchecked target(s): totally-fake-target
|
||||
```
|
||||
|
||||
The run still exits 0, so that line reads as a pass and is not one. Treat `DID NOT RUN` as **not
|
||||
checked**, always. A retrofit signed off on a scratch copy carries an unverified boundary target
|
||||
into the corpus, which is precisely the failure this gate exists to catch.
|
||||
|
||||
## Cut in this order
|
||||
|
||||
Work the list top down and stop as soon as the gate clears. The order is by ratio of tokens
|
||||
removed to behaviour lost — inverting it is how a retrofit ends up deleting the one instruction
|
||||
the skill existed to carry.
|
||||
|
||||
1. **Gotchas that paraphrase a step in the body below.** Zero information, and already a FAIL on
|
||||
its own. Delete the Gotcha, keep the step.
|
||||
2. **Spec restatements** — text that repeats a published specification, a tool's `--help`, or a
|
||||
ceiling the validator already enforces. The agent gets this right without it. Delete, or move
|
||||
the table to `references/` if a flow genuinely needs to look it up.
|
||||
3. **Capability enumeration** — in a description, the feature list after the trigger clause; in a
|
||||
body, the paragraph that recites what the skill can do. One capability clause survives in the
|
||||
description; the rest belongs in `README.md`.
|
||||
4. **Per-flow prose** — anything only one branch of the procedure ever reaches. This is the
|
||||
largest single win in most bodies, and it is a *move*, not a delete: each flow gets its own
|
||||
self-contained `references/` file, wired from a dispatch table.
|
||||
|
||||
If the body is still over after all four, the skill is doing two jobs. Split it, and say so
|
||||
rather than compressing prose until it stops being readable.
|
||||
|
||||
## What "mutually exclusive flows" means
|
||||
|
||||
Two or more flows that a single invocation cannot both take. The three-way test, copied verbatim
|
||||
from the body-discipline rubric `/skill-audit` judges against — nothing to load, it is quoted in
|
||||
full here:
|
||||
|
||||
> separate subcommands, separate input types, separate lifecycle stages
|
||||
|
||||
Any one of the three is enough. Two flows that differ only in a parameter value are one flow.
|
||||
At two or more mutually exclusive flows a dispatch table is **mandatory** regardless of word
|
||||
count, because every invocation otherwise pays for every branch it did not take.
|
||||
|
||||
## Reference-file conventions
|
||||
|
||||
The create flow owns these rules, and this flow is forbidden from reading `references/create.md`,
|
||||
so what a retrofit needs is restated here:
|
||||
|
||||
- **One topic per file.** A file mixing two concerns gets loaded for one of them and spends the
|
||||
caller's context on the other.
|
||||
- **Kebab-case filenames**, named after the topic rather than the flow that reads it —
|
||||
`body-discipline.md`, not `step-3.md`.
|
||||
- **Wire every file with the literal conditional form** ``If <condition>, read
|
||||
`references/<file>.md` ``. A generic pointer ("see `references/` for details") is a Vale error.
|
||||
- **Two hops from `SKILL.md`, never three.** A flow file may route on to a shared contract file;
|
||||
a file reachable only through two intermediates is rarely loaded when it is needed.
|
||||
- **`source_keys` frontmatter.** If the content you are moving drew on a research source, the new
|
||||
file needs top-level `source_keys:` frontmatter listing those slugs, and every slug must already
|
||||
exist as an `## <slug>` heading in `references/sources.md`. Moving sourced content out of
|
||||
`SKILL.md` without carrying its slugs across breaks the provenance chain, and `/skill-audit`
|
||||
reports the new file as an INFO with no `source_keys`.
|
||||
|
||||
## Collateral is mandatory, not optional
|
||||
|
||||
Moving content out of a `SKILL.md` leaves three files describing a structure that no longer
|
||||
exists. `/skill-audit`'s provenance check exits clean on all three of these, so nothing catches
|
||||
them for you. After every retrofit that adds, removes or renames a file:
|
||||
|
||||
- [ ] **`README.md` file table** — a row for every new `references/` file, and no row left for a
|
||||
file that is gone. Say what triggers the load, not just what the file contains.
|
||||
- [ ] **`references/README.md`**, where the skill has one — same update, same reason.
|
||||
- [ ] **`references/sources.md` → `Contributing files`** — add the new file to every slug whose
|
||||
content moved into it, and remove any file the retrofit deleted. This is the one that gets
|
||||
missed: `sources.md` keeps citing sections of `SKILL.md` that no longer exist, the
|
||||
provenance check still exits 0, and the stale claim survives review.
|
||||
- [ ] **Reachability of every relocated gate.** For each Gotcha or gate the retrofit moved out of
|
||||
the body, list the flows that need it and confirm each one reaches the surviving copy. A gate
|
||||
that lands in a single flow file is invisible to every other branch, and no gate detects
|
||||
that: `/skill-audit` reads whichever file it was handed, and the word counts improve either
|
||||
way. Where more than one flow needs it, the copy belongs in the body's common-gates section,
|
||||
not in a flow file. Grep the skill for the gate's key term and check every branch that hits
|
||||
zero.
|
||||
- [ ] Re-run `/skill-audit` and confirm its `### Provenance` dimension does not report the new
|
||||
file as missing `source_keys`.
|
||||
|
||||
## Compression must not add authority the source text didn't have
|
||||
|
||||
This one is **not** part of the checklist above, and deliberately so: it fires on a wording change
|
||||
with no file change at all, so a retrofit that adds and removes nothing still owes it.
|
||||
|
||||
The `sources.md` bullet above is about an entry going *stale* — Contributing files left uncited
|
||||
after content moves. This is a distinct failure: a compression or rewrite pass that upgrades an
|
||||
honest hedge in a Description into an unsupported confident claim, without the underlying source
|
||||
having changed at all — "no forge-specific content drawn directly from it beyond that" quietly
|
||||
becoming "Grounds Step 2's dispatch table."
|
||||
|
||||
`/skill-audit`'s provenance script does now notice this class: it diffs each slug's `Description`
|
||||
and `Contributing files` text against a base ref and raises an **INFO** when the wording changed.
|
||||
That is a prompt, not a verdict — it reports only *that* the claim moved, never whether the new
|
||||
claim is true, because a bash script can verify an entry is internally consistent and nothing more.
|
||||
Answering it is this flow's job: if a retrofit strengthens or otherwise changes the wording of a
|
||||
provenance claim, re-read the upstream research doc first and confirm the stronger wording is
|
||||
actually still true before committing it.
|
||||
|
||||
## Versioning a retrofitted skill
|
||||
|
||||
`SKILL.md` Step 4 says to bump the **patch** version on improve, which presumes there is a version
|
||||
to bump. A pre-ADR-0020 skill often carries none — `metadata.version` only became mandatory under
|
||||
ADR-0022, and this flow is exactly where those skills surface.
|
||||
|
||||
A skill with no `metadata.version` is **seeded at `"1.0.0"`, not bumped**. `"0.1.0"` is reserved
|
||||
for a skill created new by the create flow: it means "created and never yet revised", which
|
||||
understates a skill that has been through retrofit and audit passes without tracking a version.
|
||||
Add the field in this retrofit — the `skill-frontmatter` pre-commit hook blocks the commit without
|
||||
it.
|
||||
|
||||
## Worked example — a description retrofit
|
||||
|
||||
`gitea-issues` before, 827 characters, the single most common shape in the corpus:
|
||||
|
||||
```text
|
||||
Use when reading or writing Gitea issues: listing repo issues, getting a single issue's details/
|
||||
comments/labels, creating an issue, updating its state, adding or editing comments, applying
|
||||
labels via issue_write, or searching issues/PRs across repositories. Triggers on "create an
|
||||
issue", "what issues are open", "get issue #N", "close issue #N", "comment on issue #N", "search
|
||||
issues for X" — even when the user doesn't say "Gitea" explicitly. Composes gitea-labels-
|
||||
milestones for all label inference/resolution and milestone lookup — do not use this skill to
|
||||
manage label or milestone definitions themselves (create/edit/delete a label, create/close a
|
||||
milestone), that's gitea-labels-milestones directly. Do not use for pull requests (use gitea-prs)
|
||||
or for local git branch/commit work (use gitea-branches or git-branches).
|
||||
```
|
||||
|
||||
After, the 290 characters that shipped:
|
||||
|
||||
```text
|
||||
Use when reading or writing Gitea issues — "create an issue", "what issues are open", "close
|
||||
issue #N", "comment on issue #N", "search issues for X" — even when the user does not say
|
||||
"Gitea". Not pull requests -> `gitea-prs`. Not label or milestone definitions ->
|
||||
`gitea-labels-milestones`.
|
||||
```
|
||||
|
||||
The retrofit kept the quoted-phrasing register and dropped the verb list, not the other way round.
|
||||
Either register is admissible — what is banned is carrying both. Choose whichever routes better
|
||||
for the skill in hand; here the quoted user phrasings do, because they are how people actually ask.
|
||||
|
||||
What came out, and why:
|
||||
|
||||
| Removed | Why |
|
||||
|---|---|
|
||||
| The second trigger register — `Triggers on "create an issue", "what issues are open", …` | The same triggers restated as quoted user phrasings. Two registers of one trigger list is a FAIL, not a suggestion. |
|
||||
| `applying labels via issue_write` | Implementation detail. The router does not choose a skill by which MCP call it makes. |
|
||||
| `Composes gitea-labels-milestones for all label inference/resolution and milestone lookup` | A composition note. It changes no routing decision and belongs in `README.md`. |
|
||||
| The parenthetical `(create/edit/delete a label, create/close a milestone)` | Capability enumeration inside a boundary clause. The boundary needs the target, not its feature list. |
|
||||
| The `gitea-branches` / `git-branches` boundary | Dropped entirely. Neither was ever going to win an issue request, so the clause defended against nothing — an invented boundary costs characters and buys no routing accuracy. |
|
||||
| `Do not use for pull requests (use gitea-prs)` prose form | Kept, but rewritten as `Not pull requests -> \`gitea-prs\`.` The rewrite buys characters, one uniform shape for the router, **and** a stricter check: an unresolved arrow target is a blocking ERROR, while an unresolved prose target is only a SUGGESTION unless another target in the same sentence resolves. The prose form does not dangle as loudly. |
|
||||
|
||||
What stayed: one trigger clause, one capability clause, the indirect trigger (genuinely warranted
|
||||
here — people say "create an issue", not "create a Gitea issue"), and the boundary clauses.
|
||||
|
||||
## Two rules the gates enforce but the prose does not spell out
|
||||
|
||||
**Boundary clauses may be plural.** Write one per genuine near-miss — the example above carries
|
||||
two, because two different skills could each steal activations. "A boundary clause" in the
|
||||
contract means *at least one*, not *exactly one*. What is banned is a boundary clause invented for
|
||||
a skill that was never going to compete, not a second real one.
|
||||
|
||||
**Never let a hyphenated routing target wrap across lines in a folded `>` scalar.** YAML folding
|
||||
replaces the newline with a space, so `gitea-labels-` at the end of one line and `milestones` at
|
||||
the start of the next fold into `gitea-labels- milestones`. The gate then reads the target as
|
||||
`gitea-labels`, finds no such skill, and reports a dangling boundary target. This is not
|
||||
hypothetical — it is how `gitea-labels-milestones` broke (issue #100). It is fixed: the corpus
|
||||
carries no dangling target today, and the repo's test suite pins that set as empty, so a
|
||||
reintroduction fails the suite rather than joining a backlog. Reflow the line so the whole name
|
||||
sits on one of them. The same applies to any backticked skill or agent name in a description.
|
||||
@@ -34,7 +34,7 @@ source_keys:
|
||||
- **URL:** https://agentskills.io/skill-creation/best-practices.md
|
||||
- **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md
|
||||
- **Description:** Best practices for skill creators — starting from real expertise, spending context wisely, calibrating control, instruction patterns (gotchas, templates, checklists, validation loops)
|
||||
- **Contributing files:** SKILL.md, references/create.md, references/improve.md, references/contract.md, references/retrofit.md
|
||||
- **Contributing files:** SKILL.md, references/create.md, references/improve.md, references/contract.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## agentskills-optimizing-descriptions
|
||||
@@ -42,7 +42,7 @@ source_keys:
|
||||
- **URL:** https://agentskills.io/skill-creation/optimizing-descriptions.md
|
||||
- **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md
|
||||
- **Description:** How to systematically test and improve skill descriptions for triggering accuracy — eval queries, trigger rate testing, train/validation splits, optimization loop
|
||||
- **Contributing files:** SKILL.md, references/improve.md, references/contract.md, references/retrofit.md
|
||||
- **Contributing files:** SKILL.md, references/improve.md, references/contract.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## agentskills-evaluating-skills
|
||||
|
||||
@@ -165,7 +165,6 @@ cp -r "$TEMPLATES_DIR" "$TARGET"
|
||||
|
||||
# Set skill name in templates
|
||||
sed -i "s/SKILL_NAME/$SKILL_NAME/g" "$TARGET/SKILL.md"
|
||||
sed -i "s/SKILL_NAME/$SKILL_NAME/g" "$TARGET/README.md"
|
||||
sed -i "s/SKILL_NAME/$SKILL_NAME/g" "$TARGET/tests/README.md"
|
||||
|
||||
if [[ "$MODE" == "package" ]]; then
|
||||
|
||||
Reference in New Issue
Block a user