Using Dossier with Claude Code

Last Updated: 2026-06-14 Status: Active

Overview

There are two ways to use dossiers in Claude Code, and most teams use both:

Trigger skills (recommended for shareable, versioned workflows) — a thin Claude Code skill (SKILL.md) that fires on a phrase and invokes a versioned, signed dossier. This is how you turn a workflow into something installable, pinnable, and verifiable.
MCP server (for interactive discovery and authoring) — gives Claude Code native tools to search, verify, read, and run dossiers through natural conversation.

See Dossiers as Claude Code Skills below for the full trigger-skill treatment.

MCP server integration

The Dossier MCP Server integrates directly with Claude Code, enabling you to discover, verify, execute, and create dossiers through natural conversation.

Quick Start

1. Add the MCP Server

One command registers the published server globally (available across all projects):

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

Project-only alternative — create a .mcp.json in your project root:

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

Local development (building from source)

cd /path/to/ai-dossier/mcp-server
npm install && npm run build
claude mcp add dossier --scope user -- node /path/to/ai-dossier/mcp-server/dist/index.js

2. Verify Installation

Check that the server is configured:

claude mcp list

Then ask Claude:

What dossier tools are available?

Claude should list the available tools, resources, and prompts.

Available Prompts

The MCP server provides two prompts accessible via Claude Code’s prompt picker:

`execute-dossier`

Run a dossier with full verification and protocol compliance.

Arguments:

dossier_path (required): Path or URL to the dossier file

What Claude Does:

Verifies integrity (checksum) and signature
Reads the dossier content
Follows the instructions step by step
Reports results

`create-dossier`

Author a new dossier using the official template.

Arguments:

title (required): Title for the new dossier
category (optional): Category (e.g., devops, authoring)
risk_level (optional): Risk level: low, medium, high, critical

What Claude Does:

Executes the official meta-dossier template
Guides you through proper frontmatter structure
Helps calculate checksum after completion
Optionally assists with signing

Executing a Dossier

Method 1: Natural Language

Simply ask Claude to execute a dossier:

Run the dossier at examples/devops/deploy-to-aws.ds.md

Execute https://raw.githubusercontent.com/imboard-ai/ai-dossier/main/examples/authoring/create-dossier.ds.md

Method 2: Using the Prompt

Use the execute-dossier prompt directly with the path argument.

Execution Protocol

Claude will follow the Dossier Execution Protocol:

VERIFY - Check integrity and signature
- If verification fails: STOP and report the issue
- If signature is from untrusted source: Ask whether to proceed
READ - Get the dossier content and metadata
EXECUTE - Follow the instructions
- Respect risk_level warnings
- Ask for confirmation before destructive operations
- Report progress on each step
REPORT - Summarize what was accomplished

Creating a Dossier

Method 1: Natural Language

Ask Claude to create a new dossier:

Create a dossier for setting up our CI/CD pipeline

Help me create a high-risk dossier for database migration

Method 2: Using the Prompt

Use the create-dossier prompt with:

title: “CI/CD Pipeline Setup”
category: “devops”
risk_level: “medium”

What Happens

Claude will:

Reference the official meta-dossier at examples/authoring/create-dossier.ds.md
Guide you through creating proper frontmatter
Help structure the instructions
Calculate the checksum when done
Optionally assist with signing

Available Tools

The MCP server also provides these tools that Claude can use:

Tool	Description
`verify_dossier`	Check integrity (checksum) and authenticity (signature)
`read_dossier`	Get dossier content and metadata
`list_dossiers`	List dossiers in a directory

Available Resources

Claude can access these resources for context:

Resource	Description
`dossier://concept`	What are dossiers?
`dossier://protocol`	How to execute dossiers safely
`dossier://security`	Security architecture and trust model

Dossiers as Claude Code Skills

A dossier can be installed as a Claude Code Skill so it’s discovered and invoked automatically by natural language, no MCP prompt required:

ai-dossier install-skill imboard-ai/git/full-cycle-issue-skill

This writes the dossier to ~/.claude/skills/<name>/SKILL.md. From then on, Claude routes to it whenever a request matches its description.

To sync a whole machine (skills are dossiers named *-skill or tagged skill):

ai-dossier install-skill --all --owner imboard-ai   # install/refresh every skill from an owner
ai-dossier install-skill --outdated                 # refresh only installed skills with a newer registry version
ai-dossier install-skill --list                     # installed vs latest, flags BEHIND

Each install records x_source: <owner/category/name> in the skill’s frontmatter, which is what lets --outdated re-fetch it. Skills whose basename collides (e.g. published under two categories) are reported, not overwritten. All modes take --json and exit non-zero if any skill failed.

To go the other direction — publish a local skill to the registry as a versioned, signed dossier — use ai-dossier skill-export <name> --namespace <org>/skills.

The Trigger-Skill Pattern

A trigger skill is a thin SKILL.md that exists only for discovery + routing. When matched, it hands off to an executable dossier — the heavy, versioned procedure — loaded at runtime via ai-dossier run. The trigger stays tiny so Claude can hold many of them with minimal context cost.

┌─────────────────────────┐        ai-dossier run        ┌──────────────────────────┐
│  Trigger skill          │ ───────────────────────────▶ │  Executable dossier      │
│  ~/.claude/skills/…     │   (loaded only when matched)  │  imboard-ai/…@version    │
│  • name + description   │                               │  • full procedure        │
│  • flag parsing         │                               │  • all phases / steps    │
│  • one `run` call       │                               │  • versioned separately  │
└─────────────────────────┘                               └──────────────────────────┘

Why split it — the motivation. Claude Code loads skills by progressive disclosure, in three tiers (docs):

Discovery (always resident): only each skill’s name + description stay in context (the combined description/when_to_use is capped at ~1,536 characters). This is the cost you pay for every installed skill, all the time.
Activation (on trigger): when a request matches, the entire SKILL.md body loads as a single message and stays for the rest of the session — there is no partial loading of one SKILL.md.
Execution (on demand): content the body references (separate files, or — in our case — a registry dossier fetched with ai-dossier run) loads only when actually needed.

So a fat, self-contained skill spends its whole body on tier 2 the moment it fires. A trigger skill pushes the weight down to tier 3: the always-resident footprint is just the description, and the heavy procedure only enters context when the work actually starts — and can be versioned, signed, and reused independently of the trigger.

When to use a trigger skill vs. a whole skill:

Use a trigger skill → executable dossier when…	Keep it a whole skill when…
The procedure is multi-stage or long (Anthropic recommends keeping `SKILL.md` under ~500 lines)	It’s a short, self-contained procedure
The same procedure is reused by several entry points, or one entry point composes several dossiers	It runs top-to-bottom and a run uses most of the body
The procedure is versioned/shared via the registry and you want the trigger decoupled from its content	There’s nothing to reuse or version separately

A whole skill is not a context tax just by existing — its body only loads on trigger. So split for multi-stage orchestration, reuse, or independent versioning, not merely for size.

Anatomy of a trigger skill

The trigger does three things: parse flags, call ai-dossier run, and tell Claude to follow the output. Everything substantive lives in the executable dossier. Example — full-cycle-issue-skill (≈56 lines) fronting the imboard-ai/git/full-cycle-issue dossier:

# Full Cycle Issue

## Flags
- `--base <branch>`: Override the target branch

## Steps
1. Extract the issue number from the user's request
2. Run: `ai-dossier run imboard-ai/git/full-cycle-issue --pull`
3. If `--base` was provided, pass it as the base_branch parameter
4. Follow ALL phases in the workflow output. Do not skip any.

The 800+ lines of actual workflow live in the dossier, fetched only when the skill fires. Bump the dossier’s version and every trigger pointing at it picks up the change on its next run — no skill reinstall needed.

Troubleshooting

“Signature verification failed”

The dossier may be from an untrusted source. Options:

Add the signer’s key (if you trust them):
```
ai-dossier keys add "<public_key>" "<identifier>"
```
ai-dossier verify <dossier> prints this command ready to run, with the key already in the canonical base64 form. If you paste a PEM instead, put -- first — a PEM starts with - and is otherwise read as an option.
Proceed anyway (with caution):
- Claude will ask if you want to proceed with an unsigned dossier
- Review the dossier content before agreeing

“Checksum mismatch”

The dossier content has been modified since it was signed.

DO NOT EXECUTE - the content may have been tampered with.

Ask the dossier author for an updated, properly signed version.

“MCP server not responding”

Check the server is configured: claude mcp list
Verify the MCP server is built: cd mcp-server && npm run build
Remove and re-add: claude mcp remove dossier && claude mcp add dossier --scope user -- node /path/to/dist/index.js
Check logs for errors

“Unknown tool/prompt”

Ensure you’re using the latest version of the MCP server:

cd mcp-server
git pull
npm install
npm run build

Examples

Execute a Remote Dossier

Execute the dossier at https://raw.githubusercontent.com/imboard-ai/ai-dossier/main/examples/development/add-git-worktree-support.ds.md

Create a DevOps Dossier

Create a dossier called "Deploy to Production" with risk level high and category devops

List Available Dossiers

What dossiers are available in this project?

Verify Before Executing

First verify, then execute the dossier at ./my-automation.ds.md

Security Best Practices

Always let Claude verify - Don’t skip verification for convenience
Review high-risk dossiers - Read the instructions before confirming execution
Trust keys carefully - Only add public keys from sources you trust
Check signatures - Prefer signed dossiers from trusted authors
Understand risk levels - High/critical dossiers deserve extra scrutiny

Claude Code Skills - Official skill authoring + progressive disclosure
Signing Dossiers - How to sign your own dossiers
MCP Server README - Full MCP server documentation
Security Architecture - Security model details
Dossier Protocol - Complete execution protocol

Changelog

2026-06-04

Added “Dossiers as Claude Code Skills” section
Documented the Trigger-Skill Pattern (thin trigger skill → executable dossier) and its motivation via progressive disclosure

2025-11-28

Initial guide created
Documented execute-dossier and create-dossier prompts
Added troubleshooting section
Updated installation to use claude mcp add CLI command

Questions or Issues?

GitHub Discussions: https://github.com/imboard-ai/ai-dossier/discussions
Security Issues: security@imboard.ai

Rendered from docs/guides/claude-code-integration.md in the repository. Edit it there.

Using Dossier with Claude Code

Overview

MCP server integration

Quick Start

1. Add the MCP Server

2. Verify Installation

Available Prompts

execute-dossier

create-dossier

Executing a Dossier

Method 1: Natural Language

Method 2: Using the Prompt

Execution Protocol

Creating a Dossier

Method 1: Natural Language

Method 2: Using the Prompt

What Happens

Available Tools

Available Resources

Dossiers as Claude Code Skills

The Trigger-Skill Pattern

Anatomy of a trigger skill

Troubleshooting

“Signature verification failed”

“Checksum mismatch”

“MCP server not responding”

“Unknown tool/prompt”

Examples

Execute a Remote Dossier

Create a DevOps Dossier

List Available Dossiers

Verify Before Executing

Security Best Practices

Related Documentation

Changelog

2026-06-04

2025-11-28

`execute-dossier`

`create-dossier`