Dossier

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.

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"*.

Alternative: Claude Code plugin (auto-updates)

/plugin marketplace add imboard-ai/ai-dossier

/plugin install dossier-mcp-server@ai-dossier

</details>

Alternative: Manual JSON config (Claude Desktop or other MCP clients)

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:

Trigger skills bridge the two: a thin SKILL.md whose job is to invoke a versioned, signed dossier (ai-dossier run ) — 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