Source To Skill

Source-to-Skill Compiler

Transform raw source materials into a structured, validated agent skill. The pipeline distills knowledge from sources, operationalizes it into methodology, and compiles a skill that encodes what a competent practitioner needs to do — not a summary of what the sources say.

Pipeline

Sources → Inventory → Extract → Synthesize → Compile → Validate → Deliver

Follow these phases in order. Each phase has a completion gate — do not advance until the gate is met.

Phase 1: Source Inventory

Catalogue every source the user provides.

For each source, record:

After cataloguing, identify coverage gaps: topics the user expects the skill to cover that no source addresses. Flag these to the user before proceeding.

Completion gate

• Every source has an inventory entry
• Coverage gaps identified and communicated to the user

Phase 2: Knowledge Extraction

Read each source. Extract knowledge units — atomic pieces of extractable knowledge. See knowledge-spec.md for the intermediate representation format.

Extraction priorities (in order)

1. Procedures: What does the source teach you to do? Step sequences, decision points, ordering.
2. Principles: What rules or heuristics govern those procedures? The reasoning behind steps.
3. Constraints: What must hold true? Boundaries, prerequisites, invariants.
4. Concepts: Domain terms the source defines or relies on. Definitions and relationships.
5. Examples and counterexamples: Concrete cases showing correct and incorrect application.

Provenance

Every knowledge unit carries its source ID and location (chapter, timestamp, section, paragraph). Knowledge without provenance is inadmissible — discard it or ask the user to confirm the source.

Conflict detection

When sources disagree, record both positions as separate knowledge units linked by a conflicts_with relationship. Flag every conflict to the user with both positions stated. Do not silently resolve conflicts.

Source reliability

Weight knowledge units by source authority. A peer-reviewed methodology textbook outweighs a casual tutorial. When a low-authority source is the only one covering a topic, mark the resulting knowledge units as confidence: low and flag the gap.

Completion gate

• Every source fully read and extracted
• All knowledge units have provenance
• Conflicts between sources flagged to the user
• User has reviewed and resolved critical conflicts

Phase 3: Methodology Synthesis

Transform extracted knowledge units into an operational methodology — the structured workflow the compiled skill will encode.

Operationalize every procedure

For each procedure from Phase 2, produce an operational stage:

STAGE: [Name]

INPUT
- What the practitioner needs before starting this stage

STEPS
1. [Imperative action] — completion criterion: [how to know it is done]
2. [Next action] — completion criterion: [...]

DECISION POINTS
- If [condition] → [branch A path]
- If [condition] → [branch B path]

OUTPUT
- What this stage produces

VALIDATION
[ ] Checkable criterion 1
[ ] Checkable criterion 2

The driving question for every stage: "What does a competent practitioner actually need to be able to DO?"

Sequence and dependencies

Arrange stages into a dependency order. Identify which stages must precede others and which can run in parallel.

Merge and deduplicate

Multiple sources often describe the same procedure differently. Merge overlapping stages, keeping the strongest version. Preserve provenance from all contributing sources.

Completion gate

• Every procedure from Phase 2 has a corresponding operational stage
• Every stage has explicit inputs, outputs, steps, and validation criteria
• Stages are ordered by dependency (prerequisites before dependents)
• Duplicate stages merged

Phase 4: Skill Compilation

Compile the operational methodology into a proper agent skill. See compilation-guide.md for the detailed mapping from knowledge spec to skill components.

Target structure

[skill-name]/
├── SKILL.md
├── references/
│   ├── terminology.md        (if 5+ domain terms)
│   ├── examples.md           (if 2+ worked examples)
│   └── [topic-specific].md   (as needed)
└── scripts/                  (only if deterministic automation needed)

SKILL.md composition

1. Frontmatter: name and description only. Description carries trigger branches — the conditions under which the skill fires.

2. Body: The operational methodology as sequential phases. Each phase contains:

   • Steps in imperative form
   • Completion criteria on every step
   • Decision points where the workflow branches

3. Progressive disclosure: Body stays under 500 lines. Push domain glossary, extended examples, detailed schemas, and reference tables into references/ files. Point to each reference file from the body at the point where the agent needs it.

Writing discipline

Every line of the compiled skill must pass these checks:

• Imperative form: "Identify the domain experts" — not "The domain experts should be identified"
• Leading words: Use compact pretrained concepts that anchor behavior (elicit, validate, trace, decompose). Prefer real English words over coined jargon.
• Positive steering: State what to do. A prohibition earns its place only as a hard guardrail impossible to phrase positively — and even then, pair it with the positive target.
• Single source of truth: Each meaning lives in one place. If the environment already states something, the skill does not restate it.
• Operational, not descriptive: Encode capability. A stage with inputs, steps, and validation criteria is operational. "Source X says this is important" is a summary — delete it.
• Prune: Every line must change agent behavior versus the default. Delete no-ops.

Completion gate

• Complete skill directory exists
• SKILL.md body under 500 lines
• Every phase has completion criteria
• Every reference file pointed to from the body
• Skill reads as documentation for the agent, not a textbook about the domain

Phase 5: Validation

Test the compiled skill against the source material.

Source fidelity

Walk the knowledge spec. For every knowledge unit, verify the compiled skill encodes it as one of:

• An inline step or criterion
• A reference entry
• A documented exclusion with rationale

Flag any knowledge unit silently dropped.

Operational coverage

Generate 3–5 realistic test scenarios spanning the skill's intended use. For each scenario, walk through the compiled methodology and verify:

1. The skill provides sufficient guidance to handle it
2. Steps execute in the correct order
3. Decision points cover the scenario's branches
4. A practitioner following the skill would reach a correct result

Gap reporting

Identify scenarios the skill cannot handle. Report these to the user as known limitations.

Completion gate

• Every knowledge unit accounted for (encoded or explicitly excluded)
• At least 3 test scenarios walked through successfully
• Known limitations documented

Delivery

Present the compiled skill to the user with:

1. The skill directory — ready to install
2. Extraction summary — what was found across sources (count of knowledge units by type, key conflicts resolved)
3. Known limitations — scenarios the skill does not cover
4. Unresolved items — any remaining source conflicts or low-confidence areas