docs(skills): stop routing content at the README this branch deleted
skill-author still told authors to move description overflow "to the body or to README.md" while this branch deleted every per-skill README.md, every references/README.md and the README scaffold template. factory-audit's skill-file-structure.md bans non-spec files at the skill root, and the line that used to carve README out of that rule went with them. So skill-author created the file, factory-audit failed it, and nothing read it.8ce5392fixed the two scripts and missed the reference prose. The two contract.md files now differ deliberately: a skill's overflow goes to the body or a references/ file, an agent's to the body alone, because an agent is a single file with no references/ directory to disclose to. agent-description-quality.md's "the plugin's README.md" is left alone, plugin READMEs being the ones that survive. Deleting retrofit.md also dropped three instructionsbaa2f5ddid not restore with the cut list, two of which retrofit.md itself recorded as having no validator behind them: re-cite sources.md's Contributing files after content moves, since validate-provenance exits 0 on exactly that drift, and re-check a relocated gate's reachability, since a Gotcha moved into one flow's file is invisible to the others and the word counts improve either way. The third is that boundary clauses are plural — contract.md read as a cap where git-remotes carries four. Also: contract.md named an unqualified scripts/validate.sh that does not exist in skill-author, which skill-file-structure.md calls a hard error; and agent-body-and-delegation.md's simile pointed at a stale README row as the characteristic skill defect, a defect class that can no longer occur, replaced with a SKILL.md naming a references/ file that is not there. skill-author 1.0.4, agent-author 1.0.3, factory-audit 1.0.2. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NwD8Egs5r4ndqeFLmhusX2
This commit is contained in:
@@ -7,9 +7,9 @@ source_keys:
|
||||
|
||||
# The description and body contract
|
||||
|
||||
House contract. Every rule here is enforced by `/factory-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.
|
||||
House contract. Every rule here is enforced by `/factory-audit` — the counts and the boundary
|
||||
targets by `factory-audit`'s `scripts/validate.sh`, the prose patterns by the Vale styles it
|
||||
bundles, the judgment calls by its reference files.
|
||||
|
||||
## Why the budget exists
|
||||
|
||||
@@ -28,10 +28,11 @@ A description carries exactly three things:
|
||||
Focus on user intent, not the skill's internal mechanics.
|
||||
2. **At most one capability clause** — what it does, one clause, no enumeration. Be specific
|
||||
("parses and validates OpenAPI specs", not "helps with APIs").
|
||||
3. **Boundary clause** — form: `Not <thing> -> <skill-name>.` Add one only where a near-miss skill
|
||||
could steal activations.
|
||||
3. **Boundary clause** — form: `Not <thing> -> <skill-name>.` Write one per genuine near-miss
|
||||
skill that could steal activations: at least one, not exactly one — `git-remotes` carries
|
||||
four. What is banned is a clause invented for a skill that was never going to compete.
|
||||
|
||||
Banned from a description; move it to the body or to `README.md`:
|
||||
Banned from a description; move it to the body or to a `references/` file:
|
||||
|
||||
- Capability enumeration or feature lists
|
||||
- Output-format detail ("Produces a compact findings report with Why and Fix per finding")
|
||||
|
||||
Reference in New Issue
Block a user