Skip to content

skill-quality: detect and fix SKILL.md overspecification#1266

Merged
christso merged 4 commits into
mainfrom
skill-quality/overspecification-guidance
May 27, 2026
Merged

skill-quality: detect and fix SKILL.md overspecification#1266
christso merged 4 commits into
mainfrom
skill-quality/overspecification-guidance

Conversation

@christso
Copy link
Copy Markdown
Collaborator

@christso christso commented May 27, 2026

Summary

Adds overspecification detection guidance to skill-quality-checklist.md — the anti-pattern of inlining rule prose, operational procedures, and worked examples into SKILL.md when they belong in `references/`.

Motivation

WTG.AI.Prompts PR #679 turned a 33-line routing SKILL.md into a 94-line / 1168-word file by adding: a 5-item Review Checklist (each item restating a rule already in `references/`, ending with "see `references/foo.md`"), a 20-line schema-verification procedure, and a citation discipline section with worked examples. The intent was legitimate (deterministic coverage, consistent output shape) but the mechanism was wrong — inlining instead of using the lighter primitives that already exist.

Sections touched in `skill-quality-checklist.md`

  • Content Quality → Conciseness: diagnostic rule — "When SKILL.md exceeds ~500 words, the heaviest section is almost always inlined reference material — extract it"
  • Content Quality → Coverage Contracts vs. Rule Restatement (new subsection): coverage-contract pattern (one-line item + cite reference + "silence is a gap" + "say so if unavailable") vs. the anti-pattern of multi-paragraph items that duplicate `references/`
  • Anti-Patterns to Flag: two new rows — inlined rule prose; embedded operational procedures/worked examples
  • Discipline-Enforcing Skills: two new bullets — discipline patterns belong in `references/`, mark the file as always-load rather than inlining for coverage

Also included (pre-existing breakage on main)

  • Tests: fix two failures introduced by `feat(studio): default to projects dashboard ([codex] Default Studio to projects dashboard #1265)` — `resolveDashboardMode(0, {})` expectation and `resolveIndexRoute` call with wrong argument order
  • Lint: fix pre-existing biome format/type errors in `remote.ts`, `serve.ts`, `EvalDetail.tsx`, `StopRunButton.tsx`, `routes/index.tsx`

@cloudflare-workers-and-pages
Copy link
Copy Markdown

cloudflare-workers-and-pages Bot commented May 27, 2026

Deploying agentv with  Cloudflare Pages  Cloudflare Pages

Latest commit: 1d32792
Status: ✅  Deploy successful!
Preview URL: https://37315783.agentv.pages.dev
Branch Preview URL: https://skill-quality-overspecificat.agentv.pages.dev

View logs

@christso christso merged commit 0e1b9cd into main May 27, 2026
4 checks passed
@christso christso deleted the skill-quality/overspecification-guidance branch May 27, 2026 15:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant