Source To Skill

---
name: source-to-skill
description: Use when compiling raw knowledge sources (transcripts, docs, PDFs, books, video notes) into structured, operational agent skills.
author: J StaR Films / Takomi
coauthored: J StaR Films / Takomi
version: 1.0.0
---

# 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:

| Field | Content |
|---|---|
| **ID** | Short identifier (`src-01`, `src-02`, …) |
| **Type** | transcript / document / webpage / book / video-notes |
| **Title** | Source title or description |
| **Authority** | Creator and their domain credibility |
| **Coverage** | Topics this source addresses |

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](references/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](references/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