skill-optimization

What this skill does

# Skill Optimization

## BP Patterns (Best Practice Patterns)

### P1 Critical — Must fix before skill is usable

**BP-1: Negative-to-Positive Rewriting**

Convert prohibitions into actionable instructions. Agents follow positive directives more reliably than avoiding negatives.

```
BAD:  "Don't use any in TypeScript"
GOOD: "Use explicit types: unknown for external data, generics for reusable code, union types for variants"
```

**BP-2: Vague-to-Specific Conversion**

Replace ambiguous guidance with measurable criteria.

```
BAD:  "Write clean functions"
GOOD: "Function length: <50 lines ideal, <200 max. Single return type. Max 3 parameters (use options object beyond 3)."
```

**BP-3: Missing Output Format Specification**

Every skill used by an agent that produces structured output MUST define the expected format.

```
BAD:  "Report the findings"
GOOD: "Output JSON: { status, findings: [{category, severity, location, remediation}], summary }"
```

### P2 High — Should fix for production-quality skills

**BP-4: Unstructured-to-Organized**

Content should flow from general principles to specific patterns. Use consistent heading hierarchy.

```
BAD:  Mixed tips, rules, and examples in random order
GOOD: Principle → When to apply → Pattern → Example → Anti-pattern
```

**BP-5: Missing Context Provision**

State when and why a rule applies, not just what the rule is.

```
BAD:  "Use Result type for error handling"
GOOD: "Use Result type when: crossing service boundaries, parsing external input, operations with expected failure modes. Skip for: internal logic with guaranteed preconditions."
```

**BP-6: Complex-to-Decomposed**

Break complex multi-part rules into discrete, independently applicable items.

```
BAD:  "Handle errors properly with logging, user notification, and recovery"
GOOD: Three separate sections: "Error Logging" (what/when/format), "User Notification" (messages/severity), "Error Recovery" (retry/fallback/escalation)
```

### P3 Enhancement — Nice to have for polish

**BP-7: Biased Examples**

Provide examples that cover both success and failure paths, not just happy paths.

```
BAD:  Only showing successful validation
GOOD: Show validation success AND common validation failure scenarios
```

**BP-8: Missing Escalation Criteria**

Define when the agent should stop and escalate to the user instead of continuing.

```
BAD:  No mention of edge cases or uncertainty handling
GOOD: "Escalate when: security implications unclear, performance impact >10%, breaking change to public API"
```

## Editing Principles

For detailed editing principles (context efficiency, deduplication, grouping, measurability, positive form, consistent notation, explicit prerequisites, priority ordering, scope boundaries), reference **rule-editing-guide** skill.

### Skill-Specific Applications

1. **Context Efficiency**: Skill SKILL.md should be self-contained within its scope. Reference other skills by name, never duplicate content.

2. **Deduplication**: If content overlaps with another skill, reference it: "See [skill-name] skill '[section]' for details."

3. **Measurability**: Every criterion should be checkable — "Is this rule followed? Yes/No" must be answerable from the code.

4. **Scope Boundaries**: First paragraph of skill MUST state what is in scope and what is not.

5. **Expert References**: Every skill should end with "Expert References (Reasoning Calibration)" table for decision grounding.

## Grading System

### A Grade — Production Ready
- All P1 patterns (BP-1, BP-2, BP-3) resolved
- 80%+ of P2 patterns (BP-4, BP-5, BP-6) addressed
- Output format clearly specified
- Expert References section present
- No ambiguous or unmeasurable criteria

### B Grade — Usable with Gaps
- All P1 patterns resolved
- Some P2 gaps remain (1-2 unaddressed)
- Core content is clear and actionable
- Minor structural improvements possible

### C Grade — Requires Revision
- P1 patterns remaining (negative rules, vague criteria, or missing output format)
- Significant restructuring needed
- Cannot be reliably used by agents in current state

## Assessment Checklist

When evaluating a skill, check each item:

### Structure
- [ ] Frontmatter has name and description with auto-load triggers
- [ ] Description includes "Automatically loaded when..." clause
- [ ] Content flows general → specific
- [ ] Consistent heading hierarchy (H2 for sections, H3 for subsections)
- [ ] Scope clearly stated in opening paragraph

### Content Quality
- [ ] No negative-only rules (BP-1)
- [ ] All criteria are specific and measurable (BP-2)
- [ ] Output format defined if agent produces structured output (BP-3)
- [ ] Organized by topic, not chronologically (BP-4)
- [ ] Context provided for when/why rules apply (BP-5)
- [ ] Complex rules decomposed into discrete items (BP-6)

### Completeness
- [ ] Both success and failure examples included (BP-7)
- [ ] Escalation criteria defined (BP-8)
- [ ] Expert References table present
- [ ] No content duplicated from other skills

### Integration
- [ ] Referenced in skills-index.yaml with accurate tags
- [ ] Tags cover all relevant search terms
- [ ] key_sections list matches actual H2 headings