SCHEMA (input.yaml spec)  +  COMPILER (this skill)  =  One coherent unit
                              ↓
                    input.yaml (the seed)
                              ↓
                    SKILL.md (compiled output)

input.yaml  →  [Skill Compiler]  →  SKILL.md
   ↑                                    ↓
   └──── edit here ←── regenerate ──────┘

# Required fields
name: string           # Skill identifier (kebab-case)
version: string        # Semantic version (e.g., "1.0.0")
purpose: string        # One-line description of what the skill does

# Activation conditions
triggers:
  - string             # Keywords/phrases that should activate this skill
  - string             # e.g., "research", "investigate", "analyze"

# Core content
principles:            # 3-7 guiding principles
  - name: string
    description: string
    rationale: string  # Why this principle matters

workflow:              # Ordered phases of execution
  - phase: string      # Phase name
    description: string
    steps:
      - string
      - string
    outputs:           # What this phase produces
      - string

# Knowledge capture
patterns:              # Positive patterns to follow
  - name: string
    when: string       # Situation this applies
    do: string         # What to do
    why: string        # Rationale

antipatterns:          # Negative patterns to avoid
  - name: string
    description: string
    consequence: string
    instead: string

# Quality assurance
checklist:             # Verification items before completion
  - string
  - string

# Optional
examples:              # Concrete usage examples
  - scenario: string
    application: string

references:            # Sources and citations
  - string
  - string

metadata:
  domain: string       # Category (e.g., "research", "debugging", "workflow")
  energy: string       # Cognitive load: low, medium, high
  time_estimate: string # Typical duration

name: hello-world
version: 1.0.0
purpose: Demonstrate skill structure with minimal fields

triggers:
  - "hello world skill"
  - "demonstrate skill format"

principles:
  - name: Simplicity
    description: Start with the minimum viable structure
    rationale: Complexity should be added only when needed

workflow:
  - phase: Greet
    description: Produce a greeting
    steps:
      - Identify the target audience
      - Generate appropriate greeting
    outputs:
      - Greeting message

checklist:
  - Greeting is contextually appropriate
  - Tone matches audience expectations

# {Name} Skill

> Version: {version}
> Compiler: {compiler_version}
> Last Updated: {date}

{purpose}

## When to Activate

Use this skill when:
{triggers as bullet points}

## Core Principles

{for each principle}
### {N}. {principle.name}
{principle.description}

{principle.rationale as italicized note if present}
{end for}

---

## Workflow

{for each phase}
### Phase {N}: {phase.phase}

{phase.description}

{phase.steps as numbered list}

**Outputs:** {phase.outputs as inline list}
{end for}

---

## Patterns

{patterns as table: Name | When | Do | Why}

## Anti-Patterns to Avoid

{antipatterns as table: Anti-Pattern | Why It Fails | Instead}

---

## Quality Checklist

Before completing:

{checklist as checkbox list}

---

## Examples

{for each example}
**{example.scenario}**

{example.application}
{end for}

---

## References

{references as bullet list}

1. Load existing input.yaml
2. Run new compiler
3. Diff old SKILL.md vs new output
4. Review changes (human gate for major versions)
5. Replace SKILL.md
6. Update version if substance changed

I need to create a skill for: [TOPIC]

Generate an input.yaml that:
1. Captures 3-5 core principles (specific, actionable)
2. Defines a clear workflow (3-5 phases)
3. Includes patterns and anti-patterns from real experience
4. Has a concrete checklist for verification

Focus on practical wisdom, not textbook knowledge.
What do practitioners wish they knew sooner?

Compare this input.yaml against the skill-compiler spec:

[INPUT.YAML CONTENT]

Identify:
1. Missing required fields
2. Quality issues (vague principles, unbounded scope)
3. Opportunities for improvement
4. Suggested version bump if changes are needed

I just completed a task involving: [DESCRIPTION]

Key insights I gained:
[INSIGHTS]

Mistakes I made:
[MISTAKES]

Extract an input.yaml that captures this knowledge as a reusable skill.
Focus on the non-obvious learnings—things I had to discover the hard way.

name: code-review
version: 1.0.0
purpose: Systematic approach to reviewing code changes for quality and correctness

triggers:
  - "review this code"
  - "check this PR"
  - "code review"

principles:
  - name: Understand Before Judging
    description: Read the entire change before making any comments
    rationale: Context prevents nitpicking; you might comment on something explained later

  - name: Correctness Over Style
    description: Prioritize bugs and logic errors over formatting preferences
    rationale: Style is subjective and automatable; correctness is critical

  - name: Ask, Don't Tell
    description: Phrase feedback as questions when uncertain
    rationale: Reduces defensiveness, acknowledges reviewer might be missing context

workflow:
  - phase: Orientation
    description: Understand what the change does and why
    steps:
      - Read PR description and linked issues
      - Identify the type of change (feature, bug fix, refactor)
      - Note the scope (files changed, lines added/removed)
    outputs:
      - Mental model of the change
      - List of focus areas

  - phase: Deep Review
    description: Examine the code in detail
    steps:
      - Review changes file by file
      - Check for correctness, edge cases, error handling
      - Verify tests cover the changes
      - Look for security implications
    outputs:
      - List of concerns
      - Questions for author

  - phase: Feedback Synthesis
    description: Organize and deliver feedback constructively
    steps:
      - Categorize issues (blocking, suggestion, nitpick)
      - Write clear, actionable comments
      - Highlight positive aspects
    outputs:
      - Review comments
      - Overall assessment

antipatterns:
  - name: Drive-by Comments
    description: Commenting on individual lines without understanding the whole change
    consequence: Wastes author time addressing non-issues
    instead: Complete orientation phase before commenting

  - name: Style Wars
    description: Extensive feedback on formatting, naming, etc.
    consequence: Obscures important feedback, creates friction
    instead: Use automated linting; reserve review for substance

checklist:
  - Understood the purpose of the change
  - Checked for correctness issues
  - Verified test coverage
  - Feedback is actionable and respectful
  - Blocking issues clearly identified

# Code Review Skill

> Version: 1.0.0
> Compiler: skill-compiler/1.0.0
> Last Updated: 2026-01-22

Systematic approach to reviewing code changes for quality and correctness.

## When to Activate

Use this skill when:
- Review this code
- Check this PR
- Code review

## Core Principles

### 1. Understand Before Judging
Read the entire change before making any comments.

*Context prevents nitpicking; you might comment on something explained later.*

### 2. Correctness Over Style
Prioritize bugs and logic errors over formatting preferences.

*Style is subjective and automatable; correctness is critical.*

### 3. Ask, Don't Tell
Phrase feedback as questions when uncertain.

*Reduces defensiveness, acknowledges reviewer might be missing context.*

---

## Workflow

### Phase 1: Orientation

Understand what the change does and why.

1. Read PR description and linked issues
2. Identify the type of change (feature, bug fix, refactor)
3. Note the scope (files changed, lines added/removed)

**Outputs:** Mental model of the change, List of focus areas

### Phase 2: Deep Review

Examine the code in detail.

1. Review changes file by file
2. Check for correctness, edge cases, error handling
3. Verify tests cover the changes
4. Look for security implications

**Outputs:** List of concerns, Questions for author

### Phase 3: Feedback Synthesis

Organize and deliver feedback constructively.

1. Categorize issues (blocking, suggestion, nitpick)
2. Write clear, actionable comments
3. Highlight positive aspects

**Outputs:** Review comments, Overall assessment

---

## Anti-Patterns to Avoid

| Anti-Pattern | Why It Fails | Instead |
|--------------|--------------|---------|
| **Drive-by Comments** | Wastes author time addressing non-issues | Complete orientation phase before commenting |
| **Style Wars** | Obscures important feedback, creates friction | Use automated linting; reserve review for substance |

---

## Quality Checklist

Before completing:

- [ ] Understood the purpose of the change
- [ ] Checked for correctness issues
- [ ] Verified test coverage
- [ ] Feedback is actionable and respectful
- [ ] Blocking issues clearly identified