verify-team-skill-quality

Skill Quality — Agent Skill quality review

Entry/Exit

• Entry: New or modified SKILL.md, skill helper .md, skill routing description, trigger samples, or task samples
• Exit: A routable, loadable, verifiable, and maintainable Skill contract; when necessary, synchronize skills-index.json、skills-router.json、skills-lock.json
• Direction: Pass → return to the original phase; fail → send back to modify the Skill contract and re-review
• Preload: CANON.md; when modifying skills in this repository, you must also read the target skill in full
• Output path: The Skill quality report can be merged into docs/features/<name>/04-review.md or the verification record of the current task

When not to use

• The user only asks to explain a business concept, without involving Skill creation, modification, routing, or review
• The user only asks to use an existing Skill to complete a task, and no Skill contract issue has been found
• The goal is general code quality review, and verify-quality-code-quality
• The goal is project documentation quality, and reflect-team-documentation or a content review skill should be used

Iron Law

Core anchors

• Context-Dense Skill: Every token must reduce false triggering, shorten error paths, or improve execution stability.
• Routing Contract: The description states when loading is mandatory and the near-miss exclusion boundary, not a brief introduction.
• Progressive Disclosure: Keep high-frequency rules in SKILL.md; put long cases, long checklists, and theoretical explanations in auxiliary files; put deterministic repeated logic in scripts.
• Gotchas First: Prioritize local rules, counterintuitive constraints, failure cases, and red flags; delete general knowledge the model already knows.
• Output Contract: Execution-oriented and governance-oriented Skills must stably output structure and must not let the agent improvise freely.
• Eval-Driven Development: Description and process changes must have Trigger Eval and Task Eval perspectives, covering at least near-miss.

Review process

Step 1: Identify the Skill type

First determine which type of behavior the Skill changes:

Type	Purpose	Review focus
Routing-oriented	Determine whether to enter a certain type of task or route	description, near-miss, next Skill
Design-oriented	Output a plan, structure, interface, or architecture	Trade-offs, boundaries, acceptance criteria
Execution-oriented	Guide multi-step task execution	Steps, verification points, failure handling
Governance-oriented	Review, audit, regression, quality control	STOP, scoring, output contract, regression samples

If the positioning is too broad, narrow it first. Prefer narrow and stable over broad and vague.

Step 2: Review the description

The description must complete the routing decision before the body is loaded. Check:

• Whether it states the real user intent, rather than the internal implementation mechanism
• Whether it includes typical trigger words and implicit intent
• Whether to exclude near-misses, e.g. "design API contract" triggers, "implement API code" does not trigger
• Whether to avoid overcommitments like "all backend development"

For a non-compliant description, fix the description first, then review the body.

Step 3: Remove low-density content

Ask paragraph by paragraph: without this paragraph, would the agent be more likely to make mistakes?

Remove:

• General concept explanations
• Industry background
• Repeated rules
• Principles that are elegant but do not change behavior
• Basic best practices the model already knows

Keep:

• Trigger boundaries
• Local rules and gotchas
• Prohibitions
• STOP conditions
• Output templates
• Verification checklists
• Compatibility, permissions, regression constraints

Step 4: Check STOP and failure handling

The Skill must specify when to stop:

• Stop when required inputs are missing and state the missing items
• Stop when the scope does not match and hand off to an adjacent Skill
• When the user only requests a review, do not modify directly
• When side effects such as production, deployment, deletion, sending, payment, or submission are involved, there must be explicit confirmation or a phase gate
• When rules conflict, adjudicate according to the user's latest instruction, project entry point, safety constraints, and CANON
• When results cannot be verified, do not claim completion

Step 5: Check the output contract and Done When

The output contract must at least include:

## 结论
## 判断依据
## 执行结果 / 设计方案 / 评审结果
## 风险与边界
## 验收清单

Done When must be verifiable and must not be written as "looks reasonable" or "basically complete".

Step 6: Check progressive resources

• SKILL.md Put high-frequency rules and hard gates
• Auxiliary .md only holds long templates, long examples, scoring tables, and evidence formats, and is explicitly referenced by the main SKILL.md Explicit citation
• Repeated deterministic logic goes into scripts, instead of making the agent re-reason every time
• In this repository, auxiliary .md must go into skills-lock.json of auxiliaryHashes

Step 7: Check eval samples

Review from at least two angles:

• Trigger Eval: both should-trigger and should-not-trigger are covered; focus on near-misses, short inputs, colloquial inputs, and implicit intent
• Task Eval: include expected behavior, must include, must not include, done when

When there is no formal eval file, representative samples and conclusions must still be listed in the review report.

Verification failure handling

Failure scenario	Handling method
The description cannot distinguish near-misses	Rewrite the description first; do not continue optimizing the body
The body is mainly background explanation	Delete low-density paragraphs and replace them with local rules, gotchas, processes, and checkpoints
No STOP conditions	Add the four types of STOP: missing inputs, scope mismatch, high-risk side effects, and inability to verify
No output contract	Add a fixed template and Done When
Long content is crammed into SKILL.md	Split it into auxiliary .md, keep loading suggestions in the main file, and update the lock
Repeated mechanical logic relies on model reasoning	Extract it into scripts and actually run the scripts to verify
Only typical triggers are tested	Add should-not-trigger and near-miss samples

Common claims

Claim	Reality	Consequence
"Writing it in more detail is safer"	Long does not equal stable. Low-density content crowds out the task context.	After triggering, the context bloats and key red flags get diluted instead
"A brief description is enough for the description"	The description is a router, not an introduction.	It misses triggers when it should trigger, and triggers falsely when it should not
"The model understands all these best practices"	The model understands general knowledge, but does not know this project's boundaries and failure cases.	The Skill becomes an encyclopedia and cannot reliably change behavior
"Add eval later"	Without samples, there is no way to tell whether the description actually routes accurately.	Every change relies on feeling, and false-trigger regressions cannot be found
"STOP will make the agent too conservative"	STOP is a safety boundary for avoiding unauthorized execution and false completion.	When input is missing, scope is exceeded, or verification is impossible, execution continues and the result cannot be audited

Red flag

• The description only explains "what this Skill is" and does not state when to use it
• The description cannot exclude near-miss with adjacent Skills
• SKILL.md Largely explains general concepts and lacks local rules or gotchas
• No "when not to use" or STOP conditions
• No output template, Done When, or verification checklist
• After modifying a skill, not synced skills-index.json、skills-router.json or skills-lock.json
• Auxiliary .md not referenced by the main SKILL.md Reference
• Mechanical repeated logic is not scripted, and repeated manual writing has already appeared
• Claims completion when it cannot be verified

Verification checklist

• The Skill type is clear, with a narrow and stable scope
• The description states should-trigger and near-miss exclusion boundaries
• Low-value explanations have been removed or pushed down to auxiliary files
• Local rules, gotchas, prohibitions, and STOP conditions are clear
• The output contract and Done When are executable and verifiable
• progressive disclosure is layered correctly, and auxiliary files are referenced by the main SKILL.md Reference
• Repeated deterministic logic has been scripted or it is clearly explained why scripts are not used
• Trigger Eval covers should-trigger, should-not-trigger, and near-miss
• Task Eval covers expected behavior, must include, must not include, done when
• Repository changes have run scripts/generate-index.sh、scripts/generate-router.sh、scripts/update-lock.sh <skill> and ./validate; when adding a skill, update-lock.sh must automatically create a lock entry

Output template

# Skill Quality Review — <skill-name>

## Verdict
- Status: PASS / FAIL
- Skill type: routing / design / execution / governance

## Routing
- Should trigger:
- Should not trigger:
- Near-miss risks:

## Contract Findings
| Severity | Area | Finding | Fix |
|----------|------|---------|-----|
| Blocking | Description | ... | ... |

## Eval Coverage
- Trigger eval samples:
- Task eval samples:
- Missing coverage:

## Done When
- [ ] description 路由准确
- [ ] STOP / Output Contract / Done When 齐全
- [ ] index / router / lock / validate 同步完成