Skill Content Optimization

Core Philosophy

1. Evidence-Based: Grounded in prompt engineering research, applied to skill authoring
2. Concrete: Each pattern provides detection criteria and transform methods
3. Structure-Focused: Optimizes expression and organization; domain knowledge remains unchanged

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: "Do not modify the command", "Do not add flags", "Do not execute destructive operations"
• Rewrite in positive form: "Do not invent issues" → "Base every issue on BP patterns or 9 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: LLM attention mechanisms focus on negated content. Skill instructions with "don't" increase probability of the forbidden behavior.

BP-002: Vague Instructions → Specific Criteria

Skill example:

• Before: "Handle errors appropriately"
• After: "Error handling criteria: 1. try-catch for external API calls, file I/O, JSON.parse 2. Log: error.name, error.stack, timestamp 3. Re-throw with context if caller needs to handle"

Why critical for skills: Accounts for ~40% of execution variance. Every vague instruction forces LLM to guess.

BP-003: Missing Output Format → Structured Output

Skill example:

• Before: "Analyze the code for issues"
• After: "Output format: ## Issues Found with table: | Severity | Location | Description | Suggested Fix |"

Why critical for skills: Structured output constraints reduce hallucination and make skill results consistent.

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 Context → Explicit Prerequisites

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: Complex Content → Decomposed Steps

Conditional: Skip decomposition for simple reference tables or single-criteria rules.

Key insight: Goal is evaluable granularity with quality checkpoints, not decomposition for its own sake.

P3: Enhancement (Could Fix)

Incremental improvements for specific contexts.

BP-007: Biased Examples → Diverse Coverage

BP-008: No Uncertainty Permission → Explicit Escalation

Skill example:

• Before: "Determine the root cause"
• After: "Determine the root cause. If root cause is uncertain after 3 investigation cycles, report top 3 hypotheses with confidence levels and evidence for each."

9 Skill Editing Principles

Measurable quality criteria for skill content. Each principle includes a pass/fail test.

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