Skip to content
SkDD logo SkDD logo Skills-Driven Development

Skills should carry workflows

SkDD · Skills-Driven Development

Skills should carry workflows.

SkDD turns the orchestration glove inside out: the skill owns its own lifecycle, and a deterministic verifier — not the agent — decides what counts as done.

Quick start See the proof GitHub ↗
the old model

workflow owns state

skills are verbs

the runtime decides done

the new model

skill owns lifecycle

substrate governs proof

the verifier decides done

Executable proof, not a promise

One deterministic verifier. Four real receipts.

skdd proof verify recomputes a receipt's verdict from its acceptance contracts and evidence — target binding, provider independence, credential-scope separation, run chronology, digests. Agent-authored evidence cannot certify its own claim. These are the fixtures shipped in the repo, reproduced verbatim.

  1. receipts/valid-production.json ✓ verified

    Browser probe with its own identity and read-only credentials observed the outcome on the pinned production target.

  2. receipts/d1-wrong-environment.json ✗ refused

    Local SQLite evidence was offered for a Cloudflare D1 production target. Right query, wrong world.

    TARGET_MISMATCHMISSING_EVIDENCE

  3. receipts/sentry-circular-evidence.json ✗ refused

    The executor graded its own homework: evidence produced under the executor's identity and credential scope.

    CIRCULAR_EVIDENCESHARED_CREDENTIAL_SCOPEMISSING_EVIDENCE

  4. receipts/calendar-user-broken.json ✗ refused

    The build was green, but the user-visible probe failed. A green build is not a user outcome.

    EVIDENCE_FAILEDMISSING_EVIDENCE

Run the published verifier against the shipped fixtures: 
pnpm dlx @zakelfassi/skdd@1.2.0 proof verify \
  examples/proof-carrying-skill/receipts/valid-production.json \
  --skill examples/proof-carrying-skill/finish-the-loop/SKILL.md
✓ proof receipt verified

pnpm dlx @zakelfassi/skdd@1.2.0 proof verify \
  examples/proof-carrying-skill/receipts/sentry-circular-evidence.json
✗ proof receipt refused
✗ CIRCULAR_EVIDENCE: Evidence 'poller-self-report-001' was produced by the run executor.
✗ SHARED_CREDENTIAL_SCOPE: Evidence 'poller-self-report-001' shares the executor's credential scope.
✗ MISSING_EVIDENCE: Acceptance 'sentry-auth-health' has no qualifying independent evidence.

Fixtures & skill ↗ proof-receipt/v1 schema ↗ workflow-bearing-skill/v1 schema ↗

Refused and unverified are different states: refused means the verifier found disqualifying findings; unverified means no receipt was checked at all. The verifier is deterministic and portable — it never executes workflows or trusts prose.

The constitution

  1. The skill owns procedure.
  2. The contract owns done.
  3. The ledger owns history.
  4. The conductor resolves conflict.

How it fits together

Each artifact owns one thing.

SkDD already gives skills a lifecycle — forge, register, discover, evolve, archive — across a colony your agents maintain. Workflow-bearing skills extend that colony: the same SKILL.md now travels with its contract, its state, and its proof.

SKILL.md
adaptive procedure — the steps an agent follows
WORKFLOW.json
the portable lifecycle contract: acceptance, state path, terminal states
.skdd/runs/<id>/state.json
resumable local run state — survives interruption
receipt.json
the completion claim, target tuples, and evidence references
skdd proof verify
recomputes the verdict; refuses what it cannot independently confirm

Start where you are.

Install the colony

pnpm dlx @zakelfassi/skdd init --harness=claude

Scaffolds skills/, the registry, and your harness mirror. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, Goose, and Amp.

Try the verifier

git clone https://github.com/zakelfassi/skills-driven-development.git
cd skills-driven-development
pnpm dlx @zakelfassi/skdd@1.2.0 proof verify \
  examples/proof-carrying-skill/receipts/valid-production.json \
  --skill examples/proof-carrying-skill/finish-the-loop/SKILL.md

Published in @zakelfassi/skdd@1.2.0. The receipt is recomputed locally against the exact skill bytes it claims to verify.

GitHub ↗ npm: @zakelfassi/skdd ↗