{
  "markdown": "# Dossier — Portable, Signed Skills for Any AI Agent\n\n**Skills are easy to write. Dossiers make them trustworthy, versioned, and portable across every LLM tool.**\n\n[![CI](https://github.com/imboard-ai/ai-dossier/actions/workflows/ci.yml/badge.svg)](https://github.com/imboard-ai/ai-dossier/actions/workflows/ci.yml)\n[![Examples](https://github.com/imboard-ai/ai-dossier/actions/workflows/test-examples.yml/badge.svg)](https://github.com/imboard-ai/ai-dossier/actions/workflows/test-examples.yml)\n[![npm version](https://img.shields.io/npm/v/@ai-dossier/cli)](https://www.npmjs.com/package/@ai-dossier/cli)\n[![npm downloads](https://img.shields.io/npm/dm/@ai-dossier/cli)](https://www.npmjs.com/package/@ai-dossier/cli)\n[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)\n[![Spec](https://img.shields.io/badge/Dossier%20Spec-v1.0-blue)](docs/reference/README.md)\n[![MCP Ready](https://img.shields.io/badge/MCP-Ready-brightgreen)](mcp-server)\n[![Verification](https://img.shields.io/badge/Verification-Checksums%20%26%20Signatures-yellow)](docs/explanation/security-model.md)\n[![GitHub](https://img.shields.io/github/stars/imboard-ai/ai-dossier?style=social)](https://github.com/imboard-ai/ai-dossier)\n\n> **Quick Concept**\n> A dossier is a skill — a reusable instruction set an AI executes — with trust, versioning, and cross-tool portability built in.\n> Think npm or Docker Hub, but for AI skills: signed, versioned, shareable.\n\n```\n  ┌──────────────────────────────────────────────────────────────────────┐\n  │                                                                      │\n  │    Write instructions       Verify integrity       AI executes       │\n  │    in Markdown (.ds.md)     with checksums &       the workflow      │\n  │                             signatures             intelligently     │\n  │                                                                      │\n  │    ┌──────────┐    sign     ┌──────────┐   run     ┌──────────┐     │\n  │    │  Author  │ ─────────> │  Verify  │ ────────> │ AI Agent │     │\n  │    └──────────┘            └──────────┘            └──────────┘     │\n  │         │                       │                       │            │\n  │     .ds.md file            checksum +              validated         │\n  │     with JSON              signature               results with     │\n  │     frontmatter            verification            evidence         │\n  │                                                                      │\n  └──────────────────────────────────────────────────────────────────────┘\n```\n\n**New here?** → [5-min Quick Start](docs/getting-started/quick-start.md) | **Using Claude Code?** → [MCP in 60 Seconds](docs/tutorials/mcp-quickstart.md) | **Want to try now?** → [Get started in 30 seconds](#get-started)\n\n---\n\n## At a Glance\n\n```mermaid\nflowchart LR\n    A[\"📝 Create\\n.ds.md file\"] --> B[\"🔏 Sign\\nchecksum +\\nsignature\"]\n    B --> C[\"✅ Verify\\nintegrity &\\nauthenticity\"]\n    C --> D[\"🤖 Execute\\nAI runs the\\nworkflow\"]\n    D --> E[\"📋 Validate\\nsuccess criteria\\n& evidence\"]\n\n    style A fill:#e3f2fd,stroke:#1565c0,color:#0d47a1\n    style B fill:#fce4ec,stroke:#c62828,color:#b71c1c\n    style C fill:#fff3e0,stroke:#ef6c00,color:#e65100\n    style D fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20\n    style E fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c\n```\n\n**What**: Skills (`.ds.md` files) any AI agent can run — signed, versioned, portable across tools\n**Why**: A plain skill lives in one tool and anyone can tamper with it; a dossier is that same skill made verifiable, version-pinned, and shareable\n**Safety**: Built-in checksums, cryptographic signatures, and CLI verification tools\n**Works with**: Claude, ChatGPT, Cursor, any LLM — no vendor lock-in\n\n**Status**: Protocol v1.0 (stable spec) | CLI v0.14.0 | 15+ example skills | Active development\n\n> **File conventions**: Dossiers use `.ds.md` (immutable instructions) and `.dsw.md` (mutable working files). Frontmatter uses `---dossier` (JSON) instead of `---` (YAML) to avoid parser conflicts. [Learn more](docs/explanation/faq.md#what-do-the-dsmd-and-dswmd-file-extensions-mean)\n\n---\n\n## Get Started\n\n### 1. Run a dossier — zero install\n\nPick any LLM you already have and paste this:\n\n```\nAnalyze my project using the dossier at:\nhttps://raw.githubusercontent.com/imboard-ai/ai-dossier/main/examples/guides/context-engineering-best-practices.ds.md\n```\n\nThat's it. The LLM reads the dossier and follows its instructions — no tools needed.\n\nWant to verify it first?\n\n```bash\nnpx @ai-dossier/cli verify https://raw.githubusercontent.com/imboard-ai/ai-dossier/main/examples/guides/context-engineering-best-practices.ds.md\n```\n\n### 2. Add the MCP server to Claude Code\n\nOne command gives Claude Code native dossier support — discover, verify, and execute dossiers without copy-pasting URLs:\n\n```bash\nclaude mcp add dossier --scope user -- npx @ai-dossier/mcp-server\n```\n\nThen ask Claude: *\"List available dossiers\"* or *\"Run the scaffold-typescript-project dossier\"*.\n\n<details>\n<summary>Alternative: Claude Code plugin (auto-updates)</summary>\n\n```\n/plugin marketplace add imboard-ai/ai-dossier\n/plugin install dossier-mcp-server@ai-dossier\n```\n</details>\n\n<details>\n<summary>Alternative: Manual JSON config (Claude Desktop or other MCP clients)</summary>\n\nAdd to `claude_desktop_config.json` or your MCP client's config file:\n\n```json\n{\n  \"mcpServers\": {\n    \"dossier\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ai-dossier/mcp-server\"]\n    }\n  }\n}\n```\n</details>\n\n### 3. Create your own dossier\n\nInitialize dossier in your project (sets up `~/.dossier/`, hooks, and MCP config):\n\n```bash\nnpx @ai-dossier/cli init\n```\n\nThen create a dossier:\n\n```bash\nnpx @ai-dossier/cli create my-workflow\n```\n\nThis scaffolds a `.ds.md` file you can edit. A dossier is just Markdown with a JSON frontmatter block:\n\n```markdown\n---dossier\n{\n  \"title\": \"My Workflow\",\n  \"version\": \"1.0.0\",\n  \"protocol_version\": \"1.0\",\n  \"status\": \"draft\",\n  \"objective\": \"Describe what this automates\",\n  \"risk_level\": \"low\"\n}\n---\n\n# My Workflow\n\n## Actions\n1. Step one — what to do\n2. Step two — what to verify\n\n## Validation\n- Expected outcome was achieved\n```\n\nSee the [Authoring Guide](docs/guides/authoring-guidelines.md) for the full spec, or browse the [Dossier Registry](https://dossier-registry.vercel.app) for real-world examples.\n\n---\n\n## Why Use Dossier?\n\n**\"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:\n\n|  | Plain skill (`SKILL.md`) | Dossier |\n|--|--------------------------|---------|\n| **Trust** | Unsigned — anyone can tamper | Checksum + cryptographic signature, verified before run |\n| **Versioning** | Informal | Semantic versioning you can pin |\n| **Distribution** | Copy-paste / per-tool | Registry — discoverable, `ai-dossier install-skill` |\n| **Portability** | Locked to one tool | Same file runs on Claude, ChatGPT, Cursor, any LLM |\n| **Validation** | None | Built-in success criteria |\n\n**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.\n\n**\"How about AGENTS.md files?\"** Different job: `AGENTS.md` explains *your project*; a dossier automates a *workflow*. They're complementary.\n\n---\n\n## Architecture\n\n```mermaid\ngraph TB\n    subgraph Packages[\"@ai-dossier packages\"]\n        Core[\"@ai-dossier/core\\nParsing, verification,\\nlinting, risk assessment\"]\n        CLI[\"@ai-dossier/cli\\nCommand-line tool\\nverify, sign, search, run\"]\n        MCP[\"@ai-dossier/mcp-server\\nMCP integration for\\nClaude Code & others\"]\n        Registry[\"@ai-dossier/registry\\nVercel serverless API\\nDiscover & publish\"]\n    end\n\n    subgraph Inputs[\"Dossier Files\"]\n        DS[\".ds.md\\nImmutable instructions\\nJSON frontmatter + Markdown\"]\n        DSW[\".dsw.md\\nMutable working files\\nExecution state\"]\n    end\n\n    subgraph Consumers[\"AI Agents\"]\n        Claude[\"Claude Code\"]\n        ChatGPT[\"ChatGPT\"]\n        Cursor[\"Cursor\"]\n        Other[\"Any LLM\"]\n    end\n\n    DS --> Core\n    DSW --> Core\n    Core --> CLI\n    Core --> MCP\n    CLI --> Registry\n    MCP --> Claude\n    MCP --> ChatGPT\n    MCP --> Cursor\n    MCP --> Other\n    CLI -->|\"verify & run\"| Consumers\n\n    style Core fill:#e3f2fd,stroke:#1565c0,color:#0d47a1\n    style CLI fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20\n    style MCP fill:#fff3e0,stroke:#ef6c00,color:#e65100\n    style Registry fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c\n    style DS fill:#fff9c4,stroke:#f9a825,color:#f57f17\n    style DSW fill:#fff9c4,stroke:#f9a825,color:#f57f17\n```\n\n### Verification Pipeline\n\nEvery dossier goes through a multi-stage security pipeline before execution:\n\n```mermaid\nflowchart TD\n    Start([\"dossier verify file.ds.md\"]) --> Parse[\"Parse frontmatter\\n+ Markdown body\"]\n    Parse --> Checksum{\"Checksum\\nverification\"}\n\n    Checksum -->|\"SHA-256 match\"| SigCheck{\"Signature\\nverification\"}\n    Checksum -->|\"mismatch\"| Block[\"BLOCK execution\\nContent tampered\"]\n\n    SigCheck -->|\"valid + trusted\"| Risk[\"Risk assessment\"]\n    SigCheck -->|\"valid + untrusted\"| Risk\n    SigCheck -->|\"unsigned\"| Risk\n    SigCheck -->|\"invalid\"| Block\n\n    Risk -->|\"low\"| Safe[\"SAFE to execute\"]\n    Risk -->|\"medium/high\"| Caution[\"PROCEED with caution\"]\n    Risk -->|\"critical + unsigned\"| Block\n\n    style Start fill:#e3f2fd,stroke:#1565c0,color:#0d47a1\n    style Safe fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20\n    style Caution fill:#fff3e0,stroke:#ef6c00,color:#e65100\n    style Block fill:#ffebee,stroke:#c62828,color:#b71c1c\n    style Checksum fill:#f5f5f5,stroke:#616161,color:#212121\n    style SigCheck fill:#f5f5f5,stroke:#616161,color:#212121\n    style Risk fill:#f5f5f5,stroke:#616161,color:#212121\n```\n\nSee [ARCHITECTURE.md](ARCHITECTURE.md) for the full system architecture.\n\n---\n\n## Examples\n\n| Example | Use Case |\n|---------|----------|\n| [Scaffold TypeScript Project](./examples/setup/scaffold-typescript-project.ds.md) | Scaffold a production-ready TS project with CI, testing, linting |\n| [Context Engineering Best Practices](./examples/guides/context-engineering-best-practices.ds.md) | Reference guide for writing effective AI agent context files |\n\nBrowse the **[Dossier Registry](https://dossier-registry.vercel.app)** for the full collection — DevOps, databases, data science, security, and more.\n\n```bash\n# Search from the CLI\nnpx @ai-dossier/cli search deploy\n```\n\n---\n\n## Security & Verification\n\n```mermaid\nflowchart LR\n    Author[\"Author\"] -->|\"signs\"| Dossier[\".ds.md\"]\n    Dossier -->|\"distributed via\"| Registry[\"Registry / URL\"]\n    Registry -->|\"fetched by\"| CLI[\"CLI / MCP\"]\n    CLI -->|\"verifies\"| Checks[\"Checksum\\n+ Signature\\n+ Risk Level\"]\n    Checks -->|\"safe\"| Execute[\"Execute\"]\n    Checks -->|\"blocked\"| Reject[\"Reject\"]\n\n    style Author fill:#e3f2fd,stroke:#1565c0,color:#0d47a1\n    style Dossier fill:#fff9c4,stroke:#f9a825,color:#f57f17\n    style Checks fill:#fff3e0,stroke:#ef6c00,color:#e65100\n    style Execute fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20\n    style Reject fill:#ffebee,stroke:#c62828,color:#b71c1c\n```\n\n- Use the CLI tool (`ai-dossier verify`) to verify checksums/signatures before execution\n- Prefer MCP mode for sandboxed, permissioned operations\n- **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.\n- See [SECURITY_STATUS.md](./SECURITY_STATUS.md) for current guarantees and limitations\n\n---\n\n## Registry & Multi-Registry Support\n\nThe CLI supports multiple registries for discovering, publishing, and sharing dossiers across teams and organizations.\n\n```mermaid\nflowchart LR\n    CLI[\"dossier CLI\"] -->|\"parallel query\"| R1[\"Public Registry\\ndossier-registry.vercel.app\"]\n    CLI -->|\"parallel query\"| R2[\"Internal Registry\\ndossier.company.com\"]\n    CLI -->|\"parallel query\"| R3[\"Mirror Registry\\nmirror.example.com\"]\n\n    R1 -->|\"results\"| Merge[\"Merge results\\n(partial failure OK)\"]\n    R2 -->|\"results\"| Merge\n    R3 -->|\"error\"| Merge\n\n    Merge --> User[\"User sees\\ncombined results\"]\n\n    style CLI fill:#e3f2fd,stroke:#1565c0,color:#0d47a1\n    style Merge fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20\n    style R3 fill:#ffebee,stroke:#c62828,color:#b71c1c\n```\n\n- **Multi-registry**: Configure multiple registries (public, internal, mirrors) queried in parallel\n- **HTTPS enforcement**: All registry URLs must use HTTPS to protect credentials in transit\n- **Per-registry credentials**: Each registry has isolated authentication — a compromised token cannot access other registries\n- **Project-level config**: Add a `.dossierrc.json` to your project for team-shared registry settings\n\n```bash\n# Add a private registry\ndossier config --add-registry internal --url https://dossier.company.com\n\n# List configured registries\ndossier config --list-registries\n```\n\nSee the [CLI documentation](./cli/README.md#config-command) for full registry management options.\n\n---\n\n## Adopter Playbooks\n\n- **Solo Dev**: paste a `.ds.md` into your LLM and run via MCP or CLI\n- **OSS Maintainer**: add `/dossiers` + a CI check that runs the Reality Check on your README\n- **Platform Team**: start with init -> deploy -> rollback dossiers; wire secrets & scanners\n\nDetailed playbooks in [docs/guides/adopter-playbooks.md](docs/guides/adopter-playbooks.md)\n\n---\n\n## Documentation\n\n| | |\n|---|---|\n| **Getting Started** | [Quick Start](docs/getting-started/quick-start.md) · [Installation](docs/getting-started/installation.md) · [MCP in 60 Seconds](docs/tutorials/mcp-quickstart.md) · [Your First Dossier](docs/tutorials/your-first-dossier.md) · [FAQ](docs/explanation/faq.md) |\n| **Reference** | [Protocol](docs/reference/protocol.md) · [Specification](docs/reference/specification.md) · [Schema](docs/reference/schema.md) · [JSON Schema](./dossier-schema.json) · [Plan Artifacts](docs/reference/plan-artifact.md) · [Core API](docs/reference/core-api.md) · [Capability Manifest](docs/reference/capabilities.md) |\n| **Guides** | [Authoring Guidelines](docs/guides/authoring-guidelines.md) · [Dossier Guide](docs/guides/dossier-guide.md) · [CI/CD Integration](docs/guides/ci-cd-integration.md) · [Execution Tracing](docs/guides/tracing.md) · [Runstate Milestones](cli/README.md#runstate--workflow-milestones) · [Scheduler Core](cli/README.md#scheduler-core-sched) · [Adopter Playbooks](docs/guides/adopter-playbooks.md) · [Autonomous Issue Pipeline](docs/how-to/autonomous-pipeline.md) · [Examples](./examples/) |\n| **Packages** | [CLI](./cli/) · [MCP Server](./mcp-server/) · [Core Library](./packages/core/) · [Scheduler](./packages/sched/) · [Registry](./registry/) |\n| **Project** | [Architecture](ARCHITECTURE.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [Changelog](CHANGELOG.md) |\n\n---\n\n## Philosophy\n\n> \"A skill tells an agent what to do. A dossier lets you trust it.\"\n\nDossiers take the skill — a reusable instruction set any AI can run — and add the things that make it safe to share: a verifiable signature, a pinnable version, and a registry to distribute it through.\n\n**The dossier standard** enables:\n- **Trust**: cryptographic signatures and checksums, verified before execution\n- **Versioning**: semantic versions you can pin and upgrade deliberately\n- **Distribution**: a registry that makes skills discoverable and installable\n- **Portability**: any project, any workflow, any LLM — no vendor lock-in\n- **Adaptability**: agents understand context and adjust behavior\n\n---\n\n**Dossier: Portable, Verifiable Skills for Any LLM**\n*Skills you can trust.*\n\n---\n\n## License\n\nThis project is licensed under the [GNU Affero General Public License v3.0 (AGPL-3.0)](LICENSE). You are free to use, copy, modify, and distribute it, provided that any modified versions or network services using this software also make their source code available under the same license.\n\n## References\n\nSee [REFERENCES.md](REFERENCES.md) for the full list of academic references and industry research supporting the dossier approach.\n",
  "bytes": 16374,
  "sha": "da69cc168029e3d8bac73d44f7e4fe4d8c38d704058e7cbcf126a671b68190fd",
  "repo_slug": "imboard-ai/ai-dossier",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_imboard_dossier_2bf60ddf/readme"
}