Repository navigation
Concise skills: one skill-creation standard, evals, and a fleet-wide rollout #6476
Description
Umbrella issue for rewriting skill and agent instructions across this marketplace to be as short as their content allows. The brief below was locked through /planning:interview (confirmed 2026-10-07). Rollout PRs reference this issue with Refs #<this> and close nothing early.
Goal
Every line in a skill or agent body passes one test: could the model already know this? All authoring and checking skills read the same standard, and no rewrite ships unless its evals hold.
Precedence
- Official Anthropic guidance (the skills docs and the platform best-practices page).
- Matt Pocock's concise style, wherever it violates no official guidance.
- House conventions, weighed against both.
The bundled claude-api prompt-audit guide is an input to the standard. Volatile specifics, such as caps, are never hard-coded in prose; they are pointers with an as-of date and a recheck trigger.
Decisions
-
Where the standard lives:
playbooks:skill-authoringownsreference/skill-criteria.md, which absorbsauthoring-guidance.mdandauthoring-checklist.md. Every other surface cites it and doesn't restate it. -
Descriptions:
- Model-invoked: a third-person "what it does" sentence plus "Use when…", with one trigger per distinct situation.
- User-invoked: a one-line summary with no triggers.
-
Bodies:
- The deletion test decides what stays.
- Judgment work states the outcome, constraints and how to verify; exact steps are kept only for fragile operations.
- Pointer records stay.
- History notes (PR and issue numbers, incident narrative) move to the CHANGELOG or git history, never to a footer.
-
Reference files: one level deep, with nothing duplicated from SKILL.md.
-
Metadata: the explicit invocation keys stay. Any other key stays only if a registered consumer reads it. Attribution moves to
docs/upstream/. -
skill-quality:check(SKILL.md only, never agents):- fails on the platform's 1,024-character description cap and the 500-line body guidance;
- warns on size against Pocock's measured medians, on unregistered metadata keys, and on history notes.
Its numbers live in a data file, one record per value with source, as-of date and recheck trigger.
-
Agents: the criteria doc gains an agents section.
harness-config:audit-instructionsgains a report-only agent pass. Noagent-quality:checkfor now; revisit through/review:audit-enforceabilityif the same mechanical violation keeps recurring. -
Overlap map: one owner per rule across
skill-quality:check,audit-instructions,docs-hygiene:audit-noise,audit-progressive-disclosure,write-for-agents,compress,harness-ops:audit-skill-visibilityandplaybooks:skill-authoring, with no duplicated detector logic.audit-noiseroutes SKILL.md andagents/*.mdto their owners. -
Measurement, before and after each rewrite:
skill-quality:check measure-invocationtrigger probes;- the plugin's
claude plugin evalcases; - for user-invoked skills, a semantic diff of the old body against the new one, with each flagged loss labelled intended or real. Any real loss blocks the PR.
The numeric regression bar is set from the pilot baseline.
-
Synced skills (
context7:lookup,dometrain:grounding,playbooks:boris,playbooks:skill-authoring,playwright:playwright): only house-owned parts change. -
Never blocked: whichever change lands first, the other resolves conflicts and merges. That includes the live
feat/poteto-2500-prs-digestbranch.
Related
- feat(context-budget): keep plugin skill descriptions visible when the skill listing overflows #6458 (listing overflow), perf: cut what reaches the orchestrator's context across plugin skills, hooks and agents #6322 (orchestrator context), docs: tree-wide no-copy retrofit of files quoting upstream pages #5684 (no-copy retrofit): separate, complementary work.
- feat(evals): compress plugin-eval/SKILL.md (v2) with a same-day confirm run #5956 (compress
plugin-eval): absorbed into theevalsrollout PR.
Checklist
Phase 0: standard and tooling
-
playbooks:skill-authoringreference/skill-criteria.md, including the agents section (done: PR feat(skill-quality): skill-criteria standard, WARN checks and rewrite tooling for concise skills #6503) -
skill-qualitydata files (numbers, metadata registry) and the new check rules (done: PR feat(skill-quality): skill-criteria standard, WARN checks and rewrite tooling for concise skills #6503) -
audit-instructionsagent pass (done: PR feat(skill-quality): skill-criteria standard, WARN checks and rewrite tooling for concise skills #6503, rows I40-I42) - Overlap map and pointer edits;
audit-noiserouting
Pilots
- code-tidying (skills pilot) (done: PR feat(code-tidying): concise skill text measured by evals, plus outcome cases for five skills #6539)
- review (agent pilot) (done: Concise skills rollout: review (7 skills, 6 model-invoked) #6564, PR feat(review): concise skill and agent text measured by evals, plus a security case and probes #7422)
Fleet (one PR per plugin, in parallel once the pilots prove out)
- actionlint
- adhd (done: Concise skills rollout: adhd (2 skills, 2 model-invoked) #6574, PR feat(adhd): concise clarify text and descriptions measured by evals, plus outcome cases and probes #7385)
- ai-briefing
- ai-slop
- animation (done: Concise skills rollout: animation (5 skills, 4 model-invoked) #6566, PR feat(animation): concise skill text measured by evals, plus outcome cases and probes #7427)
- architecture (done: Concise skills rollout: architecture (12 skills, 11 model-invoked) #6551, PR feat(architecture): concise skill text measured by evals, plus outcome cases and probes #7437)
- attribution
- autonomy
- bash-format
- biome-format
- bugs (done: Concise skills rollout: bugs (3 skills, 2 model-invoked) #6575, PR feat(bugs): concise skill text measured by evals, plus outcome cases and probes #7393)
- code-metrics
- codebase-health
- computer-use
- context-budget (done: Concise skills rollout: context-budget (3 skills, 2 model-invoked) #6576, PR feat(context-budget): concise setup skill measured by evals, plus outcome cases and probes #7391)
- context-guard
- context7 (done: Concise skills rollout: context7 (3 skills, 2 model-invoked) #6577, PR feat(context7): concise skill text measured by evals, plus outcome cases and probes #7392)
- coupling
- debugging
- desktop-notification
- discipline (done: Concise skills rollout: discipline (18 skills, 16 model-invoked) #6548, PR feat(discipline): concise skill text measured by evals, plus outcome cases and probes #7441)
- discovery
- disk-hygiene
- docs-hygiene
- docs-naming
- domain-driven-design
- dometrain
- education (done: Concise skills rollout: education (5 skills, 3 model-invoked) #6570, PR feat(education): concise skill text measured by evals, plus outcome cases and probes #7405)
- eol-normalizer
- evals (absorbs feat(evals): compress plugin-eval/SKILL.md (v2) with a same-day confirm run #5956) (done: Concise skills rollout: evals (4 skills, 4 model-invoked) #6567, PR feat(evals): concise plugin-eval, validate and methodology text measured by evals, plus outcome cases and probes #7403; feat(evals): compress plugin-eval/SKILL.md (v2) with a same-day confirm run #5956 closed)
- event-storming
- explainer-video
- firecrawl
- fleet
- gaming
- github
- go-format
- guardrails
- harness-config
- harness-memory
- harness-ops (done: Concise skills rollout: harness-ops (15 skills, 12 model-invoked) #6550, PR feat(harness-ops): concise skill text measured by evals, plus outcome cases and probes #7434)
- implementation (done: Concise skills rollout: implementation (3 skills, 3 model-invoked) #6571, PR feat(implementation): concise skill text measured by evals, plus outcome cases and probes #7404)
- improvement
- instruction-placement
- kindle-dedrm
- knowledge (done: Concise skills rollout: knowledge (6 skills, 5 model-invoked) #6565, PR feat(knowledge): concise skill text measured by evals, plus outcome cases and probes #7420)
- machine-health
- markdown-format
- mcp-tools
- miro
- multi-agent (done: Concise skills rollout: multi-agent (5 skills, 4 model-invoked) #6568, PR feat(multi-agent): concise skill text measured by evals, plus outcome cases and probes #7402)
- mutation-testing
- naming
- overengineering (done: Concise skills rollout: overengineering (4 skills, 4 model-invoked) #6569, PR feat(overengineering): concise skill text measured by evals, plus outcome cases and probes #7400)
- performance (done: Concise skills rollout: performance (6 skills, 6 model-invoked) #6562, PR feat(performance): concise skill text measured by evals, plus outcome cases and probes #7429)
- pixel-art (done: Concise skills rollout: pixel-art (6 skills, 6 model-invoked) #6563, PR feat(pixel-art): concise skill text measured by evals, plus outcome cases and probes #7426)
- planning (done: Concise skills rollout: planning (12 skills, 11 model-invoked) #6552, PR feat(planning): concise skill text measured by evals, plus outcome cases and probes #7465)
- playbooks
- playgrounds
- playwright
- plugin-quality
- powershell-format
- prototype
- rate-limit-guard
- repo-fleet-hygiene
- repo-hygiene
- retro-audio
- ruff-format
- session-flow (done: Concise skills rollout: session-flow (17 skills, 15 model-invoked) #6549, PR feat(session-flow): concise skill text measured by evals, plus outcome cases and probes #7442)
- skill-quality
- songwriting (done: Concise skills rollout: songwriting (11 skills, 10 model-invoked) #6553, PR feat(songwriting): concise skill text measured by evals, plus outcome cases and probes #8427)
- source-control
- speech
- tdd
- testing
- toolchain (done: Concise skills rollout: toolchain (4 skills, 3 model-invoked) #6573, PR feat(toolchain): concise check and lint skills, plus outcome cases and probes #7390)
- typos-format
- user-interface
- verification
- visualization
- wizard
- work-items
- writing (done: Concise skills rollout: writing (1 skills, 1 model-invoked) #6617, PR feat(writing): concise be-concise body measured by evals, plus outcome cases and probes #8459)
- x
Next
/planning:plan turns this brief into the implementation plan, including the numeric regression bar from the pilot baseline.
Activity
github-actions commentedon Oct 7, 2026
Proposed work class: work-class: scoped
Basis: automated intake triage; the lanes App applied this class.
Size: Medium
Complexity: Low
Uncertainty: Knowable
Flags: none
Blocked by: none
That decision settles the open questions. The rewrite series is stopped. What remains is the Phase 0 overlap-map pointer edits. These are the Row 1, 6, 7 and 8 sites listed in the decision. Each site must either point at its row's owner, or the pull request body must say why the site applies its own test.
I understood this as a bounded, docs-level change across a few plugins. I found no duplicate among the open issues.
Automated triage, applied by the lanes App.
kyle-sexton commentedon Oct 7, 2026
Overlap map (Phase 0)
There is one owner per rule. Every other site that states the rule becomes a pointer edit, made in the phase that owns its plugin. Built from
git grepon 2026-10-07 at311b50704./playbooks:skill-authoringrefers to its newreference/skill-criteria.md./playbooks:skill-authoring## Descriptions//skill-quality:checkdocs/conventions/invocation-mode/README.md(Phase 1);/docs-hygiene:write-for-agents(Phase 4);naming:name-it-bettercontext/sources.md(fleet: naming)/playbooks:skill-authoring## Descriptions,## Body//skill-quality:checkconstantsdocs/migration-playbook.md(Phase 1);harness-configaudit and audit-instructions criteria (Phase 2);docs-hygieneaudit-progressive-disclosure and extract-ssot (Phase 4)/playbooks:skill-authoring## Metadata//skill-quality:checkregistry/playbooks:skill-authoring## History and provenance/ SKILL.md:/skill-quality:check;agents/*.md:/harness-config:audit-instructions/docs-hygiene:audit-noiseticket-pr-residue (Phase 4 routes SKILL.md and agents to the owners above);/code-tidying:audit-comment-residuecovers code comments, a separate domain and not a duplicate/playbooks:skill-authoring## Reference filesdocs-hygieneextract-ssot and itscontext/, audit-progressive-disclosurecontext/tier-model.md(Phase 4)/playbooks:skill-authoring## Body; audit:/docs-hygiene:audit-progressive-disclosureplugin-quality:auditreference/component-types(fleet: plugin-quality);playbooks:borisis vendored and exempt/harness-ops:audit-skill-visibilityharness-ops:audit-native-overlap,harness-memory:auditcriteria,context-budget:audit,harness-configaudit and audit-pass (fleet, per plugin);/skill-quality:checkkeeps the per-entry constant as enforcement/playbooks:skill-authoring## Body, citing the claude-apiprompt-auditguideharness-memory:auditandinstruction-placement:realignapply it to other files: these become pointers in the fleet.architecture:improve's "deletion test" is about modules, not prose, so it is not a duplicateAlso from Phase 0:
/playbooks:updatedrift check forskill-authoring: frontmatter version 1.0.0 matches upstream, but the vendor content has drifted (SHA2567b0923d8…locally vs05b4e6b7…upstream). This needs a separate sync PR and is not part of this rollout.Generated by Claude Code
feat(skill-quality): skill-criteria standard, WARN checks and rewrite…
feat(playbooks): let evals decide skill cuts in the skill criteria (#…
feat(code-tidying): concise skill text measured by evals, plus outcom…
97 remaining items
github-actions commentedon Nov 4, 2026
Outside actor.
ami-guru(id 294709261) wrote here (event: comment created) and is neither an organization member nor on the trusted-actor list.A person reviews this before any lane acts on it. Their text is not quoted here.
github-actions commentedon Nov 4, 2026
github-actions commentedon Nov 5, 2026
github-actions commentedon Nov 5, 2026