Dossier — Signed, Versioned Agent Skills for Model-Driven Orchestration

An open standard for signed, versioned agent skills, built for model-driven orchestration: the model reads the skill and decides the steps, and Dossier makes that safe to share and repeat with signed agent skills. Host skills anywhere — a GitHub repo, your own server, or the Dossier registry — and everyone installs the same version and can verify who wrote it and that it wasn't changed. Website

Quick Concept A dossier is an agent skill with a version and a signature (a .ds.md file). Copying skill files between machines and teammates works, until nobody knows which version is running or who changed it. Dossier gives every skill a pinned version and an Ed25519 signature, so everyone installs the same thing and can verify who wrote it and that it wasn't changed. Like an npm package, a dossier works wherever it lives: the format carries the version and signature, so a skill fetched from GitHub verifies the same as one installed from a registry. Signatures prove integrity and origin; they do not prevent prompt injection or make a skill safe to run.

  ┌──────────────────────────────────────────────────────────────────────┐
  │                                                                      │
  │    Write a skill (.ds.md)   Verify integrity       AI executes       │
  │    in Markdown, then sign   with checksums &       the workflow      │
  │                             signatures             intelligently     │
  │                                                                      │
  │    ┌──────────┐    sign     ┌──────────┐   run     ┌──────────┐     │
  │    │  Author  │ ─────────> │  Verify  │ ────────> │ AI Agent │     │
  │    └──────────┘            └──────────┘            └──────────┘     │
  │         │                       │                       │            │
  │     .ds.md file            checksum +              validated         │
  │     with JSON              signature               results with     │
  │     frontmatter            verification            evidence         │
  │                                                                      │
  └──────────────────────────────────────────────────────────────────────┘

New here? → 5-min Quick Start | Using Claude Code? → MCP in 60 Seconds | Want to try now? → Get started in 30 seconds

---

At a Glance

flowchart LR
    A["📝 Create\n.ds.md file"] --> B["🔏 Sign\nchecksum +\nsignature"]
    B --> C["✅ Verify\nintegrity &\nauthenticity"]
    C --> D["🤖 Execute\nAI runs the\nworkflow"]
    D --> E["📋 Validate\nsuccess criteria\n& evidence"]

    style A fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
    style B fill:#fce4ec,stroke:#c62828,color:#b71c1c
    style C fill:#fff3e0,stroke:#ef6c00,color:#e65100
    style D fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    style E fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c

What: Skills (.ds.md files) any AI agent can run — signed, versioned, portable across tools Why: A plain skill lives in one tool and anyone can tamper with it; a dossier is that same skill made verifiable, version-pinned Integrity: Built-in checksums, cryptographic signatures, and CLI verification tools Works with: Claude, ChatGPT, Cursor, any LLM — no vendor lock-in Works with Agent Skills / SKILL.md: Dossier is a layer on top of Agent Skills, not a rival format. It adds signing and versioning, and you move skills in and out with ai-dossier install-skill and ai-dossier skill-export.

Status: Protocol v1.0 (stable spec) | CLI v0.14.0 | 15+ example skills | Active development

File conventions: Dossiers use .ds.md (immutable instructions) and .dsw.md (mutable working files). Signed dossiers use standard --- YAML frontmatter in the Agent Skills layout, so each one is also a valid skill; hand-written ones can use the readable ---dossier JSON layout, which ai-dossier sign converts. Learn more

---

How it works: model-driven orchestration

In model-driven orchestration the model decides the steps, the tool calls, the retries and when the work is done. A hand-coded DAG doesn't. Dossier makes that safe to share and repeat. Every skill is signed and version-pinned. Multi-step runs sit inside a deterministic scheduler that never calls an LLM.

The model-driven approach was popularised by AWS Strands Agents. Dossier builds on it and adds signing, versioning and a deterministic shell.

| | Code-driven orchestration | Model-driven orchestration | Dossier: hybrid model-driven orchestration | |--|---------------------------|---------------------------|--------------------------------------------| | Who decides the steps | Your code: a DAG or state machine | The model, from instructions and tools | The model, inside each skill | | What wraps it | The workflow engine | Usually nothing deterministic | A deterministic scheduler (@ai-dossier/sched) that never calls an LLM | | Trust in the instructions | Code review | Whatever prompt was loaded | Skills are signed and version-pinned, verified before they run | | Example | A hand-built DAG of LLM calls | AWS Strands Agents | ai-dossier run on a signed .ds.md skill |

Dossier calls this hybrid model-driven orchestration: model-driven inside each skill, deterministic around it. Read the full explanation in Model-driven orchestration.

---

Get Started

1. Run a dossier — zero install

Pick any LLM you already have and paste this:

Analyze my project using the dossier at:
https://raw.githubusercontent.com/imboard-ai/ai-dossier/main/examples/guides/context-engineering-best-practices.ds.md

That's it. The LLM reads the dossier and follows its instructions — no tools needed.

Want to verify it first?

npx @ai-dossier/cli verify https://raw.githubusercontent.com/imboard-ai/ai-dossier/main/examples/guides/context-engineering-best-practices.ds.md

2. Add the MCP server to Claude Code

One command gives Claude Code native dossier support — discover, verify, and execute dossiers without copy-pasting URLs:

claude mcp add dossier --scope user -- npx @ai-dossier/mcp-server

Then ask Claude: "List available dossiers" or "Run the scaffold-typescript-project dossier".

<details> <summary>Alternative: Claude Code plugin (auto-updates)</summary>

/plugin marketplace add imboard-ai/ai-dossier
/plugin install dossier-mcp-server@ai-dossier

</details> <details> <summary>Alternative: Manual JSON config (Claude Desktop or other MCP clients)</summary>

Add to claude_desktop_config.json or your MCP client's config file:

{
  "mcpServers": {
    "dossier": {
      "command": "npx",
      "args": ["-y", "@ai-dossier/mcp-server"]
    }
  }
}

</details>

3. Create your own dossier

Initialize dossier in your project (sets up ~/.dossier/, hooks, and MCP config):

npx @ai-dossier/cli init

Then create a dossier:

npx @ai-dossier/cli create my-workflow

This scaffolds a .ds.md file you can edit. A dossier is just Markdown with a metadata block on top, which you can write as JSON:

---dossier
{
  "title": "My Workflow",
  "version": "1.0.0",
  "protocol_version": "1.0",
  "status": "draft",
  "objective": "Describe what this automates",
  "risk_level": "low"
}
---

# My Workflow

## Actions
1. Step one — what to do
2. Step two — what to verify

## Validation
- Expected outcome was achieved

When you sign it, ai-dossier sign rewrites the header as standard --- YAML in the Agent Skills layout (name and description at the top, the other fields under metadata as dossier.* strings) and adds a signature that covers it. The signed file passes skills-ref validate and installs into Claude Code as is. See Spec-Shaped Dossiers for the walkthrough.

See the Authoring Guide for the full spec, or browse the Dossier Registry for real-world examples.

---

Why Use Dossier?

"Isn't this just a skill?" Yes — a dossier is a skill. The difference is everything a plain skill (like a Claude Code SKILL.md) lacks:

| | Plain skill (SKILL.md) | Dossier | |--|--------------------------|---------| | Trust | Unsigned — anyone can tamper | Checksum + cryptographic signature, verified before run | | Versioning | Informal | Semantic versioning you can pin | | Distribution | Copy-paste / per-tool | Registry — discoverable, ai-dossier install-skill | | Portability | Locked to one tool | Same file runs on Claude, ChatGPT, Cursor, any LLM | | Validation | None | Built-in success criteria |

Trigger skills bridge the two: a thin SKILL.md whose job is to invoke a versioned, signed dossier (ai-dossier run <registry-path>) — you keep the natural-language trigger and gain signing, versioning, and registry distribution.

"How about AGENTS.md files?" Different job: AGENTS.md explains your project; a dossier automates a workflow. They're complementary.

---

Architecture

graph TB
    subgraph Packages["@ai-dossier packages"]
        Core["@ai-dossier/core\nParsing, verification,\nlinting, risk assessment"]
        CLI["@ai-dossier/cli\nCommand-line tool\nverify, sign, search, run"]
        MCP["@ai-dossier/mcp-server\nMCP integration for\nClaude Code & others"]
        Registry["@ai-dossier/registry\nVercel serverless API\nDiscover & publish"]
    end

    subgraph Inputs["Dossier Files"]
        DS[".ds.md\nImmutable instructions\nfrontmatter + Markdown"]
        DSW[".dsw.md\nMutable working files\nExecution state"]
    end

    subgraph Consumers["AI Agents"]
        Claude["Claude Code"]
        ChatGPT["ChatGPT"]
        Cursor["Cursor"]
        Other["Any LLM"]
    end

    DS --> Core
    DSW --> Core
    Core --> CLI
    Core --> MCP
    CLI --> Registry
    MCP --> Claude
    MCP --> ChatGPT
    MCP --> Cursor
    MCP --> Other
    CLI -->|"verify & run"| Consumers

    style Core fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
    style CLI fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    style MCP fill:#fff3e0,stroke:#ef6c00,color:#e65100
    style Registry fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c