Skill Optimization

Skill Content Optimization

Core Philosophy

1. Finding-Based: Every change resolves a recorded issue or follows a named project-specific source
2. Concrete: Each pattern provides detection criteria and transform methods
3. Structure-Focused: Optimizes expression and organization; domain knowledge remains unchanged
4. Intent-Preserving: Records the original requirements before changing structure, wording, constraints, context, or examples
5. Traceable: Connects every applied change to a finding or named project source
6. 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

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

Resolution steps (first-row findings):

1. Choose the least-restrictive sufficient criterion — the measurable if-then rule or threshold that supplies the required precision while excluding the fewest valid behaviors.
2. Record its precision contribution: the observable output difference it improves for the intended outcome.
3. Record its constraint cost: the valid solutions allowed by the original intent that it excludes.
4. Apply it only when the precision contribution is identifiable and the constraint cost preserves the original intent.
5. 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

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

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

Standard skill section order:

1. Context/Prerequisites
2. Core concepts (definitions, patterns)
3. Process/Methodology (step-by-step)
4. Output format/Examples
5. Quality checklist
6. 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

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."