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

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"]
    }
  }
}

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 <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
    style DS fill:#fff9c4,stroke:#f9a825,color:#f57f17
    style DSW fill:#fff9c4,stroke:#f9a825,color:#f57f17

Verification Pipeline

Every dossier goes through a multi-stage security pipeline before execution:

flowchart TD
    Start(["dossier verify file.ds.md"]) --> Parse["Parse frontmatter\n+ Markdown body"]
    Parse --> Checksum{"Checksum\nverification"}

    Checksum -->|"SHA-256 match"| SigCheck{"Signature\nverification"}
    Checksum -->|"mismatch"| Block["BLOCK execution\nContent tampered"]

    SigCheck -->|"valid + trusted"| Risk["Risk assessment"]
    SigCheck -->|"valid + untrusted"| Risk
    SigCheck -->|"unsigned"| Risk
    SigCheck -->|"invalid"| Block

    Risk -->|"low"| Safe["SAFE to execute"]
    Risk -->|"medium/high"| Caution["PROCEED with caution"]
    Risk -->|"critical + unsigned"| Block

    style Start fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
    style Safe fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    style Caution fill:#fff3e0,stroke:#ef6c00,color:#e65100
    style Block fill:#ffebee,stroke:#c62828,color:#b71c1c
    style Checksum fill:#f5f5f5,stroke:#616161,color:#212121
    style SigCheck fill:#f5f5f5,stroke:#616161,color:#212121
    style Risk fill:#f5f5f5,stroke:#616161,color:#212121

See ARCHITECTURE.md for the full system architecture.

Examples

Browse the Dossier Registry for the full collection — DevOps, databases, data science, security, and more.

# Search from the CLI
npx @ai-dossier/cli search deploy

Security & Verification

flowchart LR
    Author["Author"] -->|"signs"| Dossier[".ds.md"]
    Dossier -->|"distributed via"| Registry["Registry / URL"]
    Registry -->|"fetched by"| CLI["CLI / MCP"]
    CLI -->|"verifies"| Checks["Checksum\n+ Signature\n+ Risk Level"]
    Checks -->|"safe"| Execute["Execute"]
    Checks -->|"blocked"| Reject["Reject"]

    style Author fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
    style Dossier fill:#fff9c4,stroke:#f9a825,color:#f57f17
    style Checks fill:#fff3e0,stroke:#ef6c00,color:#e65100
    style Execute fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    style Reject fill:#ffebee,stroke:#c62828,color:#b71c1c

• Use the CLI tool (ai-dossier verify) to verify checksums/signatures before execution
• Prefer MCP mode for sandboxed, permissioned operations
• External reference declaration: Dossiers that fetch or link to external URLs must declare them in external_references with trust levels. The linter flags undeclared URLs, and the MCP server's read_dossier tool returns security_notices for any undeclared external URLs found in the body. This mitigates transitive trust risks from unvetted external content.
• See SECURITY_STATUS.md for current guarantees and limitations

Registry & Multi-Registry Support

The CLI supports multiple registries for discovering, publishing, and sharing dossiers across teams and organizations.

flowchart LR
    CLI["dossier CLI"] -->|"parallel query"| R1["Public Registry\ndossier-registry.vercel.app"]
    CLI -->|"parallel query"| R2["Internal Registry\ndossier.company.com"]
    CLI -->|"parallel query"| R3["Mirror Registry\nmirror.example.com"]

    R1 -->|"results"| Merge["Merge results\n(partial failure OK)"]
    R2 -->|"results"| Merge
    R3 -->|"error"| Merge

    Merge --> User["User sees\ncombined results"]

    style CLI fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
    style Merge fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    style R3 fill:#ffebee,stroke:#c62828,color:#b71c1c

• Multi-registry: Configure multiple registries (public, internal, mirrors) queried in parallel
• HTTPS enforcement: All registry URLs must use HTTPS to protect credentials in transit
• Per-registry credentials: Each registry has isolated authentication — a compromised token cannot access other registries
• Project-level config: Add a .dossierrc.json to your project for team-shared registry settings

# Add a private registry
dossier config --add-registry internal --url https://dossier.company.com

# List configured registries
dossier config --list-registries

See the CLI documentation for full registry management options.

Adopter Playbooks

• Solo Dev: paste a .ds.md into your LLM and run via MCP or CLI
• OSS Maintainer: add /dossiers + a CI check that runs the Reality Check on your README
• Platform Team: start with init -> deploy -> rollback dossiers; wire secrets & scanners

Detailed playbooks in docs/guides/adopter-playbooks.md

Documentation

Philosophy

"A skill tells an agent what to do. A dossier lets you trust it."

Dossiers take the agent skill and add what copying files lacks: a pinnable version, a verifiable signature (so you can tell who wrote it and that it was not changed), and a registry to install it from. Verification proves integrity and origin; it does not prevent prompt injection or make a skill safe to run.

The dossier standard enables:

• Trust: cryptographic signatures and checksums, verified before execution
• Versioning: semantic versions you can pin and upgrade deliberately
• Distribution: a registry that makes skills discoverable and installable
• Portability: any project, any workflow, any LLM — no vendor lock-in
• Adaptability: agents understand context and adjust behavior

Dossier: Signed, Versioned Agent Skills for Model-Driven Orchestration Skills you can trust.

FAQ

What is model-driven orchestration?

It is orchestration where the model decides the steps, tool calls, retries and when the work is done, instead of a hand-coded DAG or state machine. The term was popularised by AWS Strands Agents. Dossier adds signed, version-pinned skills and a deterministic scheduler around the model. See How it works.

How do I sign an agent skill?

Signed agent skills start as a .ds.md file. Sign it with the CLI to add a checksum and an Ed25519 signature, and anyone can then verify it before running. See the 5-min Quick Start and Create your own dossier.

How