Skill Content Optimization
Core Philosophy
- Finding-Based: Every change resolves a recorded issue or follows a named project-specific source
- Concrete: Each pattern provides detection criteria and transform methods
- Structure-Focused: Optimizes expression and organization; domain knowledge remains unchanged
- Intent-Preserving: Records the original requirements before changing structure, wording, constraints, context, or examples
- Traceable: Connects every applied change to a finding or named project source
- Self-Contained: Keeps every pure skill executable when loaded alone; duplication across independently loaded pure skills is valid when each copy is required for standalone execution
Content Optimization Patterns
P1: Critical (Must Fix)
Issues that directly reduce LLM execution accuracy when consuming the skill.
BP-001: Negative Instructions → Positive Form
| Detection |
Transform |
| "don't", "do not", "never", "avoid" in skill instructions |
State the desired action or allowed state first. Preserve an explicit prohibition only when the violation is an irreversible operational action, the caller cannot normally recover it, and a positive-only rewrite would blur the boundary. Pair the prohibition with the safe alternative and the condition that authorizes crossing the boundary. Rewrite reviewable quality policies in positive form. |
Exception boundary examples:
- Permitted: "Move obsolete records to the recoverable archive. Do not permanently delete them unless the user explicitly authorizes permanent deletion."
- Rewrite in positive form: "Do not invent issues" → "Base every issue on BP patterns or 10 principles", "Do not skip P1 issues" → "Evaluate all P1 issues in every review mode", "Do not give grade A when P1 exists" → "Assign grade A only when P1 count is zero"
Quality policies, role boundaries, scoring criteria, and general work rules always use positive form. Outputs that the caller validates, overwrites, or discards are never irreversible.
Skill example:
- Before: "Don't use generic variable names"
- After: "Use descriptive variable names that reflect purpose (e.g.,
userId not x)"
Why critical for skills: A prohibition alone leaves the executable target state unspecified.
BP-002: Vague Instructions → Specific Criteria
| Detection |
Transform |
| Vague term ("appropriate", "good", "proper", "best", "should be clear") that leaves a decision the intended outcome requires, where plausible interpretations would materially change execution or verification |
Resolve it with the least-restrictive sufficient criterion, following the resolution steps below |
| Unspecified format, length, scope, tone, or success criteria whose plausible interpretations satisfy the intended outcome equally well |
Treat as acceptable flexibility; add a constraint only when one interpretation is required (for a format a downstream consumer requires, see BP-003) |
Resolution steps (first-row findings):
- Choose the least-restrictive sufficient criterion — the measurable if-then rule or threshold that supplies the required precision while excluding the fewest valid behaviors.
- Record its precision contribution: the observable output difference it improves for the intended outcome.
- Record its constraint cost: the valid solutions allowed by the original intent that it excludes.
- Apply it only when the precision contribution is identifiable and the constraint cost preserves the original intent.
- When input or project context cannot determine the decision, record the required source instead of guessing.
Skill exception: Expressions that the LLM can resolve unambiguously from input context (e.g., "where the user left gaps" when the user's prompt is available for comparison) are not vague — they describe a deterministic operation, not a subjective judgment.
Skill example:
- Before: "Handle errors appropriately"
- After (criteria derived from a named source): "Follow the project error-handling policy (docs/error-handling.md): wrap external API calls, file I/O, and JSON.parse in try-catch; log error.name, error.stack, and timestamp; re-throw with context when the caller must handle it."
- After (no source available): "Record 'error-handling policy' as the required source instead of inventing try-catch targets, log fields, or thresholds."
Why critical for skills: A vague instruction forces the model to choose an outcome-relevant behavior without a supplied criterion.
BP-003: Missing Output Format → Structured Output
| Detection |
Transform |
| Skill describes what to do but not the expected deliverable format |
Add an output section defining the structure, fields, and ordering required by the output consumer (parsing, routing, comparison, verification), rather than selecting a format by convention |
For a skill review, the output contract contains BP-001 through BP-009 coverage, stable finding IDs, severity, location, quoted evidence, accepted declines, preservation requirements, unresolved inputs, and the final grade. For skill creation, the output is the complete SKILL.md content plus any required same-directory references or scripts.
Skill example:
- Before: "Analyze the code for issues"
- After (format required by the review-report consumer): "Emit
## Issues Found as a table the report renderer parses: | Severity | Location | Description | Suggested Fix |"
Why critical for skills: Structured output constraints reduce hallucination and make skill results consistent.
BP-009: Unbounded Work Generation → Proportionate Work
| Detection |
Transform |
| A finding, possibility, or technically valid improvement becomes mandatory without changing the outcome, a required boundary, a real consumer, or necessary proof |
Treat it as a candidate; retain required work and allow no-change, reuse, and evidence-backed decline |
| Research breadth determines implementation or artifact scope |
Stop when the required outcome is observable; discovery alone does not expand the work |
Why critical for skills: Capable models execute implied obligations, so unsupported possibilities can manufacture work without improving the result.
P2: High Impact (Should Fix)
Issues that reduce skill effectiveness when addressed.
BP-004: Unstructured Content → Organized Format
| Detection |
Transform |
| Wall of text without headings |
Apply standard section order (see below) |
| Multiple topics mixed in one section |
Split into distinct headed sections |
| No tables for reference data |
Convert lists of criteria/patterns to tables |
Standard skill section order:
- Context/Prerequisites
- Core concepts (definitions, patterns)
- Process/Methodology (step-by-step)
- Output format/Examples
- Quality checklist
- References
Conditional: Skip restructuring if skill is under 30 lines and covers a single topic.
BP-005: Missing or Excess Context → Necessary and Sufficient Context
| Detection |
Transform |
| Skill assumes knowledge not stated |
Add Prerequisites section listing required context |
| Domain terms used without definition |
Add definitions inline or in a glossary table. Skill exception: Terms within the LLM's baseline knowledge (widely-used technical terminology, standard domain vocabulary) require no definition. Only project-specific terms, internal naming conventions, or domain jargon outside common LLM training data need explicit definition. |
| No "when to use" guidance |
Add trigger conditions with concrete scenarios |
| Context that has no downstream effect and is duplicated, distracting, or unactionable |
Condense repeated facts into one operative statement; keep raw background behind a path or reference when only an extracted fact is needed; name the source for project-specific facts |
Skill example:
- Before: "Apply the strangler pattern for migration"
- After: "Prerequisite: Existing monolith with identifiable module boundaries. When to use: Replacing legacy module while maintaining production traffic."
BP-006: Missing or Excess Procedural Control → Evidence-Guided Gates
| Detection |
Transform |
| A later action would be invalid without prerequisite evidence |
Add a gate naming the required evidence and transition condition |
| Authority, irreversible action, machine-consumed contract, or completion proof is implicit |
Make that boundary explicit |
| A reversible choice is prescribed as a mandatory route |
State the purpose, evidence, and selection criteria; let the model choose the route |
| A gate requires a specific label or artifact despite semantically equivalent evidence |
Accept the equivalent evidence unless a machine consumer requires the exact form |
Key insight: Control the boundary and required evidence, not a predicted path between them.
For skill creation, use three gates in order:
- Analysis gate: Original requirements are recorded, BP-001 through BP-009 are covered, every issue has evidence, and no unresolved input blocks faithful work.
- Optimization gate: Every finding has one applied/skipped resolution, each change is traceable, and all preservation requirements remain represented.
- Balance gate: Intent preservation, decision sufficiency, information density, constraint necessity, work proportionality, and traceability pass before the result is final.
For review-driven repair, use the current review as analysis evidence and apply the optimization and balance gates to the accepted repair scope.
P3: Enhancement (Could Fix)
Incremental improvements for specific contexts.
BP-007: Unnecessary or Biased Examples → Minimal Necessary Examples
| Detection |
Transform |
| Examples restate behavior already known to the LLM |
Replace with a concise rule or consumer-required output shape, and remove the examples |
| Examples encode a domain-, product-, or organization-specific mapping, non-obvious exception, or boundary a rule cannot express |
Keep the smallest set that covers those mappings; map each example to the ambiguity it removes |
| Multiple examples remove the same ambiguity, or all share the same surface pattern |
Reduce to the smallest covering set; add a different case only when it removes a distinct ambiguity |
BP-008: No Uncertainty Permission → Explicit Escalation
| Detection |
Transform |
| Skill demands definitive answers always |
Classify claims as observed, inferred, or unknown; add escalation criteria for ambiguous cases |
| No "when to stop" guidance |
When an unknown blocks the next step, stop at that gate and name the exact evidence or user decision required to continue |
Skill example:
- Before: "Determine the root cause"
- After: "Classify the root cause as observed, inferred, or unknown. When missing evidence blocks the next step, stop at the current gate and name the exact evidence or user decision required to continue."
10 Skill Editing Principles
Measurable quality criteria for skill content. Each principle includes a pass/fail test.
| # |
Principle |
Pass Criteria |
Fail Example |
| 1 |
Context efficiency |
Every sentence supplies non-baseline knowledge, a decision rule, a required boundary, or execution evidence. |
Restates baseline behavior without a supplied failure, review finding, or project requirement showing an execution effect |
| 2 |
Deduplication |
No concept is explained twice at the same abstraction level within one skill. Duplication across independently loaded pure skills is valid when each copy is required for standalone execution; evaluate those copies for semantic consistency rather than replacing them with sibling-skill references |
The same rule appears twice in one skill without adding a distinct execution role |
| 3 |
Grouping |
Related criteria in single section (minimize read operations) |
Scattered error handling rules across 4 sections |
| 4 |
Measurability |
Criteria name observable evidence, deterministic decision rules, or justified thresholds |
"Write clean code" without an observable condition |
| 5 |
Positive form |
Instructions state what to do (BP-001 applied) |
"Don't use any" instead of "Use only X" |
| 6 |
Consistent notation |
Uniform heading levels, list styles, table formats |
Mix of -, *, 1. in same context |
| 7 |
Explicit prerequisites |
Project-specific and non-baseline prerequisites are stated or linked; baseline technical knowledge is left concise |
Uses "DI" without defining Dependency Injection |
| 8 |
Priority ordering |
Most important items first, exceptions last |
Edge cases before common patterns |
| 9 |
Scope boundaries |
Explicitly state what the skill covers and the conditions that activate conditional content. A pure skill contains the context required for standalone execution. Cross-skill references are reserved for skills whose role is orchestration or skill selection |
A pure skill omits an operative rule because another independently loaded skill also contains it |
| 10 |
Work proportionality |
Every required artifact, test, gate, or decision changes the outcome, a boundary, a consumer result, or necessary proof |
Requires all findings or technically valid improvements to be implemented |
References
- Creating skills: See references/creation-guide.md for generation flow and description guidelines
- Reviewing skills: See references/review-criteria.md for evaluation flow and grading
1---2name: skill-optimization3description: Evaluates and optimizes skill file quality using 9 content patterns and 10 editing principles. Use when creating skills, refining skill content, or auditing skill quality.4---56# Skill Content Optimization78## Core Philosophy9101. **Finding-Based**: Every change resolves a recorded issue or follows a named project-specific source112. **Concrete**: Each pattern provides detection criteria and transform methods123. **Structure-Focused**: Optimizes expression and organization; domain knowledge remains unchanged134. **Intent-Preserving**: Records the original requirements before changing structure, wording, constraints, context, or examples145. **Traceable**: Connects every applied change to a finding or named project source156. **Self-Contained**: Keeps every pure skill executable when loaded alone; duplication across independently loaded pure skills is valid when each copy is required for standalone execution1617## Content Optimization Patterns1819### P1: Critical (Must Fix)2021Issues that directly reduce LLM execution accuracy when consuming the skill.2223#### BP-001: Negative Instructions → Positive Form2425| Detection | Transform |26|-----------|-----------|27| "don't", "do not", "never", "avoid" in skill instructions | State the desired action or allowed state first. Preserve an explicit prohibition only when the violation is an irreversible operational action, the caller cannot normally recover it, and a positive-only rewrite would blur the boundary. Pair the prohibition with the safe alternative and the condition that authorizes crossing the boundary. Rewrite reviewable quality policies in positive form. |2829**Exception boundary examples**:30- Permitted: "Move obsolete records to the recoverable archive. Do not permanently delete them unless the user explicitly authorizes permanent deletion."31- Rewrite in positive form: "Do not invent issues" → "Base every issue on BP patterns or 10 principles", "Do not skip P1 issues" → "Evaluate all P1 issues in every review mode", "Do not give grade A when P1 exists" → "Assign grade A only when P1 count is zero"3233Quality policies, role boundaries, scoring criteria, and general work rules always use positive form. Outputs that the caller validates, overwrites, or discards are never irreversible.3435**Skill example:**36- Before: "Don't use generic variable names"37- After: "Use descriptive variable names that reflect purpose (e.g., `userId` not `x`)"3839**Why critical for skills**: A prohibition alone leaves the executable target state unspecified.4041#### BP-002: Vague Instructions → Specific Criteria4243| Detection | Transform |44|-----------|-----------|45| Vague term ("appropriate", "good", "proper", "best", "should be clear") that leaves a decision the intended outcome requires, where plausible interpretations would materially change execution or verification | Resolve it with the **least-restrictive sufficient criterion**, following the resolution steps below |46| Unspecified format, length, scope, tone, or success criteria whose plausible interpretations satisfy the intended outcome equally well | Treat as acceptable flexibility; add a constraint only when one interpretation is required (for a format a downstream consumer requires, see BP-003) |4748**Resolution steps** (first-row findings):491. Choose the least-restrictive sufficient criterion — the measurable if-then rule or threshold that supplies the required precision while excluding the fewest valid behaviors.502. Record its **precision contribution**: the observable output difference it improves for the intended outcome.513. Record its **constraint cost**: the valid solutions allowed by the original intent that it excludes.524. Apply it only when the precision contribution is identifiable and the constraint cost preserves the original intent.535. When input or project context cannot determine the decision, record the required source instead of guessing.5455**Skill exception**: Expressions that the LLM can resolve unambiguously from input context (e.g., "where the user left gaps" when the user's prompt is available for comparison) are not vague — they describe a deterministic operation, not a subjective judgment.5657**Skill example:**58- Before: "Handle errors appropriately"59- After (criteria derived from a named source): "Follow the project error-handling policy (docs/error-handling.md): wrap external API calls, file I/O, and JSON.parse in try-catch; log error.name, error.stack, and timestamp; re-throw with context when the caller must handle it."60- After (no source available): "Record 'error-handling policy' as the required source instead of inventing try-catch targets, log fields, or thresholds."6162**Why critical for skills**: A vague instruction forces the model to choose an outcome-relevant behavior without a supplied criterion.6364#### BP-003: Missing Output Format → Structured Output6566| Detection | Transform |67|-----------|-----------|68| Skill describes what to do but not the expected deliverable format | Add an output section defining the structure, fields, and ordering required by the output consumer (parsing, routing, comparison, verification), rather than selecting a format by convention |6970For a skill review, the output contract contains BP-001 through BP-009 coverage, stable finding IDs, severity, location, quoted evidence, accepted declines, preservation requirements, unresolved inputs, and the final grade. For skill creation, the output is the complete `SKILL.md` content plus any required same-directory references or scripts.7172**Skill example:**73- Before: "Analyze the code for issues"74- After (format required by the review-report consumer): "Emit `## Issues Found` as a table the report renderer parses: | Severity | Location | Description | Suggested Fix |"7576**Why critical for skills**: Structured output constraints reduce hallucination and make skill results consistent.7778#### BP-009: Unbounded Work Generation → Proportionate Work7980| Detection | Transform |81|-----------|-----------|82| A finding, possibility, or technically valid improvement becomes mandatory without changing the outcome, a required boundary, a real consumer, or necessary proof | Treat it as a candidate; retain required work and allow no-change, reuse, and evidence-backed decline |83| Research breadth determines implementation or artifact scope | Stop when the required outcome is observable; discovery alone does not expand the work |8485**Why critical for skills**: Capable models execute implied obligations, so unsupported possibilities can manufacture work without improving the result.8687### P2: High Impact (Should Fix)8889Issues that reduce skill effectiveness when addressed.9091#### BP-004: Unstructured Content → Organized Format9293| Detection | Transform |94|-----------|-----------|95| Wall of text without headings | Apply standard section order (see below) |96| Multiple topics mixed in one section | Split into distinct headed sections |97| No tables for reference data | Convert lists of criteria/patterns to tables |9899**Standard skill section order:**1001. Context/Prerequisites1012. Core concepts (definitions, patterns)1023. Process/Methodology (step-by-step)1034. Output format/Examples1045. Quality checklist1056. References106107**Conditional**: Skip restructuring if skill is under 30 lines and covers a single topic.108109#### BP-005: Missing or Excess Context → Necessary and Sufficient Context110111| Detection | Transform |112|-----------|-----------|113| Skill assumes knowledge not stated | Add Prerequisites section listing required context |114| Domain terms used without definition | Add definitions inline or in a glossary table. **Skill exception**: Terms within the LLM's baseline knowledge (widely-used technical terminology, standard domain vocabulary) require no definition. Only project-specific terms, internal naming conventions, or domain jargon outside common LLM training data need explicit definition. |115| No "when to use" guidance | Add trigger conditions with concrete scenarios |116| Context that has no downstream effect and is duplicated, distracting, or unactionable | Condense repeated facts into one operative statement; keep raw background behind a path or reference when only an extracted fact is needed; name the source for project-specific facts |117118**Skill example:**119- Before: "Apply the strangler pattern for migration"120- After: "**Prerequisite**: Existing monolith with identifiable module boundaries. **When to use**: Replacing legacy module while maintaining production traffic."121122#### BP-006: Missing or Excess Procedural Control → Evidence-Guided Gates123124| Detection | Transform |125|-----------|-----------|126| A later action would be invalid without prerequisite evidence | Add a gate naming the required evidence and transition condition |127| Authority, irreversible action, machine-consumed contract, or completion proof is implicit | Make that boundary explicit |128| A reversible choice is prescribed as a mandatory route | State the purpose, evidence, and selection criteria; let the model choose the route |129| A gate requires a specific label or artifact despite semantically equivalent evidence | Accept the equivalent evidence unless a machine consumer requires the exact form |130131**Key insight**: Control the boundary and required evidence, not a predicted path between them.132133For skill creation, use three gates in order:1341. **Analysis gate**: Original requirements are recorded, BP-001 through BP-009 are covered, every issue has evidence, and no unresolved input blocks faithful work.1352. **Optimization gate**: Every finding has one applied/skipped resolution, each change is traceable, and all preservation requirements remain represented.1363. **Balance gate**: Intent preservation, decision sufficiency, information density, constraint necessity, work proportionality, and traceability pass before the result is final.137138For review-driven repair, use the current review as analysis evidence and apply the optimization and balance gates to the accepted repair scope.139140### P3: Enhancement (Could Fix)141142Incremental improvements for specific contexts.143144#### BP-007: Unnecessary or Biased Examples → Minimal Necessary Examples145146| Detection | Transform |147|-----------|-----------|148| Examples restate behavior already known to the LLM | Replace with a concise rule or consumer-required output shape, and remove the examples |149| Examples encode a domain-, product-, or organization-specific mapping, non-obvious exception, or boundary a rule cannot express | Keep the smallest set that covers those mappings; map each example to the ambiguity it removes |150| Multiple examples remove the same ambiguity, or all share the same surface pattern | Reduce to the smallest covering set; add a different case only when it removes a distinct ambiguity |151152#### BP-008: No Uncertainty Permission → Explicit Escalation153154| Detection | Transform |155|-----------|-----------|156| Skill demands definitive answers always | Classify claims as observed, inferred, or unknown; add escalation criteria for ambiguous cases |157| No "when to stop" guidance | When an unknown blocks the next step, stop at that gate and name the exact evidence or user decision required to continue |158159**Skill example:**160- Before: "Determine the root cause"161- After: "Classify the root cause as observed, inferred, or unknown. When missing evidence blocks the next step, stop at the current gate and name the exact evidence or user decision required to continue."162163## 10 Skill Editing Principles164165Measurable quality criteria for skill content. Each principle includes a pass/fail test.166167| # | Principle | Pass Criteria | Fail Example |168|---|-----------|---------------|--------------|169| 1 | Context efficiency | Every sentence supplies non-baseline knowledge, a decision rule, a required boundary, or execution evidence. | Restates baseline behavior without a supplied failure, review finding, or project requirement showing an execution effect |170| 2 | Deduplication | No concept is explained twice at the same abstraction level within one skill. Duplication across independently loaded pure skills is valid when each copy is required for standalone execution; evaluate those copies for semantic consistency rather than replacing them with sibling-skill references | The same rule appears twice in one skill without adding a distinct execution role |171| 3 | Grouping | Related criteria in single section (minimize read operations) | Scattered error handling rules across 4 sections |172| 4 | Measurability | Criteria name observable evidence, deterministic decision rules, or justified thresholds | "Write clean code" without an observable condition |173| 5 | Positive form | Instructions state what to do (BP-001 applied) | "Don't use any" instead of "Use only X" |174| 6 | Consistent notation | Uniform heading levels, list styles, table formats | Mix of `-`, `*`, `1.` in same context |175| 7 | Explicit prerequisites | Project-specific and non-baseline prerequisites are stated or linked; baseline technical knowledge is left concise | Uses "DI" without defining Dependency Injection |176| 8 | Priority ordering | Most important items first, exceptions last | Edge cases before common patterns |177| 9 | Scope boundaries | Explicitly state what the skill covers and the conditions that activate conditional content. A pure skill contains the context required for standalone execution. Cross-skill references are reserved for skills whose role is orchestration or skill selection | A pure skill omits an operative rule because another independently loaded skill also contains it |178| 10 | Work proportionality | Every required artifact, test, gate, or decision changes the outcome, a boundary, a consumer result, or necessary proof | Requires all findings or technically valid improvements to be implemented |179180## References181182- **Creating skills**: See [references/creation-guide.md](references/creation-guide.md) for generation flow and description guidelines183- **Reviewing skills**: See [references/review-criteria.md](references/review-criteria.md) for evaluation flow and grading
shinpr