v1.0.0 to v1.0.0

---

name: source-to-skill

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