1# Skill Change Rubric
2 
3Use this rubric after a source passes content curation. It decides whether the extracted mechanism should change the published skill corpus.
4 
5## Hard Gates
6 
7| Gate | Pass | Fail |
8| --- | --- | --- |
9| S1 Distinct Activation | The change has a clear trigger or improves an existing trigger | No clear activation scenario |
10| S2 Implementable Guidance | The change tells an agent what to do, when to do it, and what to avoid | Adds only background knowledge |
11| S3 Corpus Fit | The change belongs in an existing skill or justifies a new skill boundary | Duplicates existing content without improvement |
12| S4 Evidence Traceability | Every non-obvious claim maps to a retrieved source or internal example | Unsupported or uncited claim |
13| S5 Maintainer Burden | The claim is stable enough for `SKILL.md` or isolated in references if volatile | Adds brittle numbers or vendor-specific churn to core instructions |
14 
15Any failed gate routes to `HUMAN_REVIEW` or `REJECT`; do not publish automatically.
16 
17## Scoring
18 
19| Dimension | Weight | What To Check |
20| --- | --- | --- |
21| Actionability | 30% | Can a future agent apply this without additional research? |
22| Relevance | 25% | Does it improve context engineering, harness engineering, evaluation, memory, tools, or agent architecture? |
23| Non-Duplication | 20% | Does it add a new mechanism, failure mode, or sharper operating rule? |
24| Evidence | 15% | Is the claim backed by reproducible artifacts, benchmarks, or credible production experience? |
25| Skill Ergonomics | 10% | Does it keep discovery, line count, and progressive disclosure clean? |
26 
27Score each dimension 0, 1, or 2. Approve only when weighted total is at least 1.4 and no hard gate fails.
28 
29## New Skill vs Existing Skill
30 
31Update an existing skill when:
32 
33- The mechanism shares the same activation scenario.
34- The current skill already owns the concept.
35- The update is a sharper guideline, gotcha, example, or reference.
36 
37Create a new skill only when:
38 
39- The activation scenario is distinct and likely to be recognized by future agents.
40- The workflow has its own operating sequence.
41- Combining it with an existing skill would blur boundaries or exceed the 500-line budget.
42 
43Keep as reference-only when:
44 
45- The source is credible but volatile.
46- The mechanism is interesting but not yet an operating rule.
47- Evidence is useful for background but not enough for published instructions.
48 
49## Required Proposal Fields
50 
51Every proposed skill change must include:
52 
53```yaml
54target: "new skill | existing skill | reference only"
55target_path: ""
56activation_trigger: ""
57mechanism: ""
58evidence:
59  - source_url: ""
60    retrieved: true
61    supports: ""
62proposed_delta:
63  section: ""
64  change_type: "add | update | remove"
65  summary: ""
66risks:
67  - ""
68review_decision: "approve | human_review | reject"
69```
70 
71## Failure Modes
72 
731. **Encyclopedia bloat**: Adding every interesting paper turns skills into literature reviews. Only publish mechanisms that change agent behavior.
742. **Claim rot**: Model-specific numbers age quickly. Put volatile evidence in dated references, not timeless guidance.
753. **Trigger collision**: Similar descriptions cause agents to activate the wrong skill. Keep skill boundaries sharper than taxonomy labels.
764. **Reference laundering**: Secondary summaries can point to primary sources but should not carry technical claims alone.
775. **One-source overfit**: A single credible source can justify human review, but broad guidance should have either reproduced evidence or multiple converging sources.
78