skillfold

You have a dozen agents in scattered Markdown files. How do you know they're wired correctly? How do you validate that Agent A's output types match Agent B's input? How do you catch cycles or unreachable nodes before runtime?

Native platforms make it easy to define individual agents and skills. What they don't solve is the coordination layer between agents: typed state, execution flows, conditional routing, and compile-time validation. Skillfold fills that gap. Declare your pipeline in YAML, validate it at compile time, and output native SKILL.md files for every agent. No runtime, no daemon, no SDK.

The Problem

You wire three agents together by hand. The engineer writes state.code, the reviewer reads it, and a conditional routes back on failure. Everything lives in separate Markdown files with no shared schema, no validation, and no way to check correctness before you run it.

• Does the reviewer actually read the field the engineer writes?
• If you rename a state field, which agents break?
• Is there a path from every node to end, or did you leave one dangling?
• Can two agents write the same field in parallel?

These are coordination problems, and they only get worse as the pipeline grows.

The Fix

Declare everything in one YAML config. The compiler validates it at compile time and outputs native agent files.

# skillfold.yaml
skills:
  atomic:
    planning: ./skills/planning
    coding: ./skills/coding
    review: ./skills/review
  composed:
    engineer:
      compose: [planning, coding]
      description: "Implements the plan and writes tests."
    reviewer:
      compose: [review]
      description: "Reviews code for correctness and quality."

state:
  Review:
    approved: bool
    feedback: string
  code: { type: string }
  review: { type: Review }

team:
  flow:
    - engineer:
        writes: [state.code]
      then: reviewer
    - reviewer:
        reads: [state.code]
        writes: [state.review]
      then:
        - when: review.approved == false
          to: engineer
        - when: review.approved == true
          to: end

npx skillfold

The compiler checks that every state read has a matching write, every transition target exists, every cycle has an exit condition, and no two agents write the same field in parallel. If anything is wrong, you get an error at build time instead of a broken pipeline at runtime.

Quick Start

npx skillfold init my-team   # scaffold a starter pipeline
cd my-team
npx skillfold                # compile it

For a step-by-step walkthrough, see the Getting Started guide. To compile directly to your platform, see the Integration Guide.

[!TIP] Add team.orchestrator: orchestrator and the orchestrator's compiled SKILL.md gets a generated execution plan with numbered steps, state tables, and conditional branches.

$ npx skillfold init demo --template dev-team
skillfold: project initialized
  -> skillfold.yaml

Next: cd demo && npm install skillfold && npx skillfold

$ cd demo && npm install skillfold && npx skillfold --target claude-code
skillfold: compiled dev-team
  -> .claude/skills/planner/SKILL.md
  -> .claude/skills/engineer/SKILL.md
  -> .claude/skills/reviewer/SKILL.md
  -> .claude/skills/orchestrator/SKILL.md
  -> .claude/agents/planner.md
  -> .claude/agents/engineer.md
  -> .claude/agents/reviewer.md
  -> .claude/commands/run-pipeline.md
  3 agents, 5 skills (2 shared). ~79 lines deduplicated.

$ ls .claude/agents/
engineer.md    planner.md    reviewer.md

$ head -20 .claude/agents/engineer.md
<!-- Generated by skillfold v1.23.0 from dev-team (skillfold.yaml). Do not edit directly. -->
---
name: engineer
description: Implements the plan by writing production code and tests.
model: inherit
color: green
---

# engineer

Implements the plan by writing production code and tests.

## Reads

- `state.plan`

## Writes

- `state.implementation`

$ npx skillfold list
dev-team