skill-forge

Lattice Skill Forge

Core responsibility: Create the right files with the right structure for a new Lattice skill.

Input: A description of what the skill should do and when it should trigger.

Output: One or more skill files written to the correct path:

• Atom → skills/atoms/{name}/SKILL.md + skills/atoms/{name}/references/defaults.md
• Molecule → skills/molecules/{name}/SKILL.md
• Refiner → skills/refiners/{name}/SKILL.md + skills/refiners/{name}/assets/template.md

How to verify this skill did its job:

• All required files exist at the correct paths
• Folder name matches name: frontmatter exactly
• All tier-required sections are present in correct order
• No placeholder content — all sections contain real, specific content

---

Step 1: Understand intent and select tier

Ask the user: "What should this skill do, and when should it trigger? Describe it briefly."

From the description, determine the tier:

State your read and confirm with the user. Get explicit tier agreement before proceeding.

---

Step 2: Requirements alignment (molecules and refiners only)

Before writing a single line of SKILL.md, agree on the design.

Check knowledge-base/ for an existing requirements doc:

ls knowledge-base/ | grep -i {name}

If found → read it, summarise key design decisions, confirm they still reflect intent.

If not found → resolve these questions through conversation before writing:

For a molecule:

• Which atoms does it compose? (Read skills/atoms/ to see what exists.)
• Is it generative (produces code/artifacts, linear flow) or planning/interactive (produces living documents, confirmation gates at each phase)?
• What does it write to .lattice/? Which subfolder? (Must be a named subfolder, never the root.)
• What is the session resume behavior — how does it handle an interrupted session?

For a refiner:

• Which atom does it configure? (A refiner must have an atom that reads its output.)
• What paths.{snake_case_key} config key does it add to .lattice/config.yaml?
• What sections does the interview template cover?
• Overlay/override — which is the default mode?

Write a one-paragraph design summary and confirm with the user.

Do NOT write SKILL.md until design is confirmed.

---

Step 3: Read current conventions

Read PROJECT.md — the Skill Conventions section. Always read it fresh; never rely on memory.

Note the current skill counts (atoms/molecules/refiners) — they will need updating in PROJECT.md after creation, but that is skill-align's job.

---

Step 4: Write the skill files

Writing an Atom

skills/atoms/{name}/SKILL.md — sections in this exact order:

1. YAML frontmatter — name (lowercase-hyphenated), description (include trigger phrases)
2. Config Resolution — always this pattern:
   • Check .lattice/config.yaml for paths.{config_key}
   • If found: read doc, check mode: overlay (merge with defaults) or mode: override (replace)
   • If not found: read ./references/defaults.md
3. Self-Validation Checklist — numbered items, bold label, imperative STOP language, clear pass/fail condition and fix per item
4. Active Anti-Pattern Scan — checkbox format (- [ ] **Name**: what it looks like → fix), minimum 5 items
5. Ambiguity Signals — genuine gray areas where two valid approaches exist; resolution guidance for each
6. Core Principle — what the atom governs, what it does NOT govern (boundary with other atoms)

skills/atoms/{name}/references/defaults.md — the embedded defaults:

• Numbered sections (§1, §2...) matching what a future refiner would produce
• Opinionated, specific content — not placeholders
• End with an attribution line

Writing a Molecule

skills/molecules/{name}/SKILL.md:

1. YAML frontmatter — name, description with trigger phrases
2. Required Skills — list every atom as framework:{name} with always/conditional qualifier
3. Mode Detection (if the molecule has modes) — how modes are invoked, what each changes
4. Workflow — numbered steps with clear inputs and outputs per step

Generative molecule conventions (code-forge, bug-fix, refactor-safely pattern):

• Linear numbered steps, no confirmation gates
• Pause only on genuine judgment calls via framework:collaborative-judgment
• No session resume check needed

Planning/interactive molecule conventions (design-blueprint, requirement-forge pattern):

• Step 1 MUST check for an existing output document. If found: read it, determine earliest incomplete step, resume from there
• Every phase MUST have three things: (1) present the output, (2) ask a specific targeted question, (3) hard gate: "Do NOT advance to Step N until the user explicitly confirms."
• Can exit early — partial output is a valid outcome
• Always writes to a named .lattice/{subfolder}/ — never to .lattice/ root

Writing a Refiner

skills/refiners/{name}/SKILL.md — cover all of these:

• What it produces (output path, two modes, config key, which atom reads it)
• Scope clarification (what this refiner does NOT configure)
• Check for existing doc before starting interview
• Mode selection conversation (overlay vs override, when to use each)
• Facilitation approach (one section at a time, defaults-first, record decisions not discussion)
• Section-by-section guide (reference ./assets/template.md and its Interview Guidance comments)
• Output assembly rules (overlay: only changed sections; override: all sections)
• Config update instructions (write paths.{key} to .lattice/config.yaml)
• Document quality checks (one checklist per mode)

skills/refiners/{name}/assets/template.md:

• Full document structure with <!-- INTERVIEW GUIDANCE: --> comments per section
• Each guidance block contains: default content, what to ask, probing questions, what is customisable vs. fixed
• Overlay preamble and override preamble (separate blocks, clearly labeled)
• Footer with project/date/mode placeholders
• INTERVIEW GUIDANCE comments are stripped from the final produced document

---

Step 5: Confirm files are complete

Before finishing, verify:

• All required files exist at the correct paths
• Folder name = name: frontmatter field (exactly, character by character)
• description: contains trigger phrases — what a user would actually type to invoke this
• All tier-specific sections are present in the correct order
• For atoms: defaults.md exists and has §-numbered sections with real content
• For refiners: template.md exists with Interview Guidance comments in every section
• For planning molecules: every phase has the three-part confirmation gate pattern
• No section contains placeholder text ("TBD", "TODO", "add content here")

Report what was created and where. Do not run validation, sync, or deploy — those are separate steps.