From 54d7bd80baa04836843e7f3c1996e54567a16874 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Sun, 16 Aug 2026 20:45:19 +0000 Subject: [PATCH] docs: rule host built-ins out of the routing target universe MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes the second open design decision on PR #103. The `/compact` finding was recorded as a false positive needing an allowlist or a suppression mechanism. It is neither: the routing universe is the apm marketplace, so a target either resolves to a skill or an agent or it does not resolve, and `/compact`, `/clear` and `/init` are Claude Code slash commands with no counterpart in Copilot CLI or Codex. `.apm/` source compiles for all three, so a vendor-neutral description routing to one is a portability defect and the hard FAIL is a true positive. An allowlist was rejected for a concrete reason, not a stylistic one: it answers a different question ("does this exist on some host?"), it cannot answer that portably from a single source file, and it goes stale the next time a host ships a command — reintroducing the same-commit-two-verdicts failure ADR-0020 already closed for deployed trees. Nothing is blocked today: zero of the 43 descriptions name a host built-in, and an author who needs to mention one writes it un-slashed, which is not route notation and carries no routing claim. Recorded in ADR-0020 and in both author-facing contract references, so the next agent reads the decision rather than "fixing" the gate. ADR: 0020 Co-Authored-By: Claude Opus 5 (1M context) --- ...0020-skill-description-and-body-context-contract.md | 10 ++++++++++ .../.apm/skills/agent-author/references/contract.md | 6 ++++++ .../.apm/skills/skill-author/references/contract.md | 6 ++++++ .../skills/agent-author/references/contract.md | 6 ++++++ .../skills/skill-author/references/contract.md | 6 ++++++ 5 files changed, 34 insertions(+) diff --git a/docs/adr/0020-skill-description-and-body-context-contract.md b/docs/adr/0020-skill-description-and-body-context-contract.md index 601eb12..19853b4 100644 --- a/docs/adr/0020-skill-description-and-body-context-contract.md +++ b/docs/adr/0020-skill-description-and-body-context-contract.md @@ -129,6 +129,16 @@ clause**, and a **boundary clause**. Capability enumeration, output-format detai dependency, and none needs to. Verified: a tree holding only `plugins/` and the root `apm.yml`, with no `.claude/` or `.agents/` anywhere, now produces findings identical to the working tree — 26 description FAILs, 9 body FAILs, 2 dangling targets, 0 missing references, 58 SUGGESTIONs. +- **The universe is the apm marketplace, and nothing else.** A routing target resolves to a skill or + an agent, or it does not resolve. Host built-ins are deliberately outside it: `/compact`, `/clear` + and `/init` are Claude Code slash commands with no counterpart in Copilot CLI or Codex, so a + vendor-neutral `.apm/` description routing to one is a portability defect and the hard FAIL is a + true positive, not a false one. An allowlist of known built-ins was **rejected**: it answers a + different question ("does this exist on *some* host?"), it cannot answer that portably from a + single source file, and it goes stale the next time a host ships a command — reintroducing the + same-commit-two-verdicts failure the bullet above exists to close. An author who needs to mention + one writes it un-slashed (``the `compact` built-in``), which is not route notation and makes no + routing claim. - **Blocking is scoped to a sentence, which makes sentence boundaries load-bearing.** A prose-form target earns a hard error only when its own sentence names another target that *resolves*; route notation (`/name`, `→ name`) is exempt and always blocks. So the splitter is part of the contract, diff --git a/plugins/kyberforge/.apm/skills/agent-author/references/contract.md b/plugins/kyberforge/.apm/skills/agent-author/references/contract.md index a128364..50f6397 100644 --- a/plugins/kyberforge/.apm/skills/agent-author/references/contract.md +++ b/plugins/kyberforge/.apm/skills/agent-author/references/contract.md @@ -70,6 +70,12 @@ that package declares in `apm.yml` under `dependencies.apm`. A sibling plugin in therefore resolves; a skill in an unrelated repo does not. A target outside that universe sends the router nowhere. Verify it before writing it — do not invent a plausible sibling. +That universe is the apm marketplace and stops there. A **host built-in is not a routing target**: +`/compact`, `/clear` and `/init` are Claude Code slash commands with no counterpart in Copilot CLI +or Codex, and `.apm/` source compiles for all three, so routing to one is a portability defect. The +gate is right to fail it and there is no allowlist. If a built-in genuinely needs mentioning, write +it un-slashed — ``the `compact` built-in`` — which makes no routing claim and is not checked. + **Length.** 250 characters SUGGESTION, 400 characters FAIL, counting the frontmatter value only with YAML folding resolved. Treat 250 as the target: the SUGGESTION tier is what moves the corpus average, the FAIL tier only stops outliers. diff --git a/plugins/kyberforge/.apm/skills/skill-author/references/contract.md b/plugins/kyberforge/.apm/skills/skill-author/references/contract.md index b41ee89..986514d 100644 --- a/plugins/kyberforge/.apm/skills/skill-author/references/contract.md +++ b/plugins/kyberforge/.apm/skills/skill-author/references/contract.md @@ -57,6 +57,12 @@ therefore resolves; a skill in an unrelated repo does not. A boundary clause nam outside that universe sends the router nowhere and fails the audit. Check the target exists before writing it — do not invent a plausible sibling name. +That universe is the apm marketplace and stops there. A **host built-in is not a routing target**: +`/compact`, `/clear` and `/init` are Claude Code slash commands with no counterpart in Copilot CLI +or Codex, and `.apm/` source compiles for all three, so routing to one is a portability defect. The +gate is right to fail it and there is no allowlist. If a built-in genuinely needs mentioning, write +it un-slashed — ``the `compact` built-in`` — which makes no routing claim and is not checked. + **Length.** 250 characters SUGGESTION, 400 characters FAIL, counting the frontmatter value only with YAML folding resolved. The agentskills.io 1,024-character spec limit is unchanged and sits above both. The SUGGESTION tier is the one that moves the average; treat 250 as the target and 400 diff --git a/plugins/kyberforge/skills/agent-author/references/contract.md b/plugins/kyberforge/skills/agent-author/references/contract.md index a128364..50f6397 100644 --- a/plugins/kyberforge/skills/agent-author/references/contract.md +++ b/plugins/kyberforge/skills/agent-author/references/contract.md @@ -70,6 +70,12 @@ that package declares in `apm.yml` under `dependencies.apm`. A sibling plugin in therefore resolves; a skill in an unrelated repo does not. A target outside that universe sends the router nowhere. Verify it before writing it — do not invent a plausible sibling. +That universe is the apm marketplace and stops there. A **host built-in is not a routing target**: +`/compact`, `/clear` and `/init` are Claude Code slash commands with no counterpart in Copilot CLI +or Codex, and `.apm/` source compiles for all three, so routing to one is a portability defect. The +gate is right to fail it and there is no allowlist. If a built-in genuinely needs mentioning, write +it un-slashed — ``the `compact` built-in`` — which makes no routing claim and is not checked. + **Length.** 250 characters SUGGESTION, 400 characters FAIL, counting the frontmatter value only with YAML folding resolved. Treat 250 as the target: the SUGGESTION tier is what moves the corpus average, the FAIL tier only stops outliers. diff --git a/plugins/kyberforge/skills/skill-author/references/contract.md b/plugins/kyberforge/skills/skill-author/references/contract.md index b41ee89..986514d 100644 --- a/plugins/kyberforge/skills/skill-author/references/contract.md +++ b/plugins/kyberforge/skills/skill-author/references/contract.md @@ -57,6 +57,12 @@ therefore resolves; a skill in an unrelated repo does not. A boundary clause nam outside that universe sends the router nowhere and fails the audit. Check the target exists before writing it — do not invent a plausible sibling name. +That universe is the apm marketplace and stops there. A **host built-in is not a routing target**: +`/compact`, `/clear` and `/init` are Claude Code slash commands with no counterpart in Copilot CLI +or Codex, and `.apm/` source compiles for all three, so routing to one is a portability defect. The +gate is right to fail it and there is no allowlist. If a built-in genuinely needs mentioning, write +it un-slashed — ``the `compact` built-in`` — which makes no routing claim and is not checked. + **Length.** 250 characters SUGGESTION, 400 characters FAIL, counting the frontmatter value only with YAML folding resolved. The agentskills.io 1,024-character spec limit is unchanged and sits above both. The SUGGESTION tier is the one that moves the average; treat 250 as the target and 400