dotagent-pack

Placeholder package and planning repo for a portable subagent packaging standard and installer CLI.

Status

This package name is currently being reserved for upcoming development.

Today, dotagent-pack is a minimal placeholder npm package so the name can be claimed early.

Planned direction:

• portable .agent packages for specialist subagents
• an installer CLI exposed as npx dotagent-pack ...
• adapters for target runtimes like Claude, Codex/OpenAI, Cursor, and similar environments

Vision

dotagent-pack aims to define a vendor-neutral way to package specialist AI subagents as portable .agent bundles and install them into target agent runtimes with an npx utility.

The end state is a workflow like:

npx dotagent-pack install ./customer-research.agent --target claude
npx dotagent-pack install ./customer-research.agent --target codex
npx dotagent-pack install ./customer-research.agent --target cursor

The portable package is the source of truth. Runtime-specific files are generated by adapters.

Problem statement

Today, agent runtimes package reusable specialists in incompatible ways.

• Claude subagents are runtime-native markdown definitions with frontmatter
• OpenAI/Codex-style agents vary by harness and provider conventions
• Cursor relies on its own project context, rules, and MCP wiring
• Skills, tools, commands, and memory all differ by platform

That makes it hard to build a reusable specialist once and install it anywhere.

This project explores a portable package standard that can represent a specialist subagent as a capability bundle, then adapt it into each runtime.

Design goals

• Package specialist subagents, not generic assistants
• Support both open-ended natural language invocation and optional structured invocation
• Keep schemas optional, not mandatory
• Treat packaged skills as a core primitive
• Treat MCP declarations as the core portability layer for external capabilities
• Allow packaged scripts and helper assets as first-class contents
• Keep runtime-specific install details in adapters
• Support install, validate, pack, upgrade, uninstall, and inspect flows through a CLI

Explicit decisions for v0

1. Authoring model: folder-first

The canonical source form is a folder-based package checked into git.

Example:

customer-research/
  agent.yaml
  agent.md
  skills/
  mcp/
  scripts/
  templates/
  examples/

A .agent file can later be an archive/export form, but the folder is the primary authoring shape.

Why:

• easier to author
• easier to diff and review
• easier to test and iterate
• fits normal git workflows

2. Installer model: adapters + local registry

The installer should:

• adapt the portable package into a target runtime
• maintain a local machine-readable registry of installed packages

Why:

• enables install, list, upgrade, uninstall, and inspect flows
• avoids making runtime projections the only source of lifecycle state

3. Executable assets: first-class

Packages may include scripts and helper executables as first-class contents.

Why:

• many useful specialist subagents need reference scripts, transforms, validators, or helpers
• packaging only prompts and MCP declarations is too limiting for real-world capability bundles

Constraint:

• the package must declare executable assets explicitly
• target adapters decide how those assets are exposed or restricted

4. Manifest format: YAML

The package manifest should be YAML in v0.

Why:

• easier for humans to author and review
• better suited to package metadata than embedding everything in markdown frontmatter
• keeps package-manager concerns separate from behavioral instructions

Core package model

A portable subagent package is a capability bundle that may include:

• identity and metadata
• behavioral instructions
• packaged skills
• MCP dependency declarations
• scripts and helper assets
• templates and examples
• optional schemas/contracts
• adapter/runtime hints

It is not just a prompt, and it is not necessarily a typed function.

Proposed v0 layout

my-subagent/
  agent.yaml
  agent.md
  skills/
    analyze/
      SKILL.md
  mcp/
    servers.yaml
  scripts/
    normalize.py
  templates/
    output.md
  examples/
    example-task.md

File roles

agent.yaml

The machine-facing package manifest.

Responsibilities:

• package identity
• package version
• package format version
• bundled asset declarations
• dependency declarations
• interaction mode declarations
• target adapter hints
• install lifecycle metadata

agent.md

The human-facing subagent definition.

Responsibilities:

• subagent purpose
• invocation guidance
• core behavioral instructions
• execution philosophy
• deliverable expectations

This keeps the behavioral definition readable while avoiding overloading markdown frontmatter with installer and lifecycle concerns.

Proposed manifest shape

Illustrative v0 sketch:

format: dotagent/v0
kind: subagent
name: customer-research
version: 0.1.0
summary: Research-oriented subagent that gathers, analyzes, and synthesizes customer and market information.

entrypoint:
  instructions: agent.md

interaction:
  mode: open
  structured:
    inputSchema: null
    outputSchema: null

contents:
  skills:
    - path: skills/analyze
  mcp:
    - path: mcp/servers.yaml
  scripts:
    - path: scripts/normalize.py
      language: python
      purpose: Normalize raw CSV exports before synthesis
  templates:
    - path: templates/output.md
  examples:
    - path: examples/example-task.md

dependencies:
  mcp:
    - id: web-research
      purpose: search and fetch public web data
      requiredTools:
        - search
        - fetch
      transports:
        - type: stdio
          command: npx
          args: ["-y", "@acme/web-research-mcp"]

adapters:
  claude:
    enabled: true
  codex:
    enabled: true
  cursor:
    enabled: true

install:
  exposeScripts: true
  postInstall: []

Interaction modes

Open mode

The subagent accepts a natural-language task and performs work using its packaged capabilities.

This should be first-class in the standard.

Structured mode

The subagent may optionally declare typed input/output schemas for runtimes that support structured invocation.

This should remain optional.

Why schemas are optional

Many specialist subagents are better described as:

• given a task
• use these capabilities
• produce the deliverable

Forcing a rigid function signature on every package would make the standard weaker, not stronger.

MCP declaration direction

MCP should be declared by capability intent, not only by raw endpoint.

Illustrative model:

dependencies:
  mcp:
    - id: sales-data
      purpose: pull subscription and revenue metrics
      requiredTools:
        - run_sql
        - list_tables
      transports:
        - type: http
          url: https://example.com/mcp
        - type: stdio
          command: npx
          args: ["-y", "@acme/sales-mcp"]

This preserves semantic meaning while giving adapters flexibility.

Skills as a core primitive

Packaged skills should be treated as first-class subagent contents.

Why:

• they encode reusable workflows
• they can bundle instructions, references, scripts, and examples
• they match how specialist capabilities are already being shared in practice

Adapter model

The portable package is not the same as the installed runtime form.

Claude adapter

Could generate or install:

• a Claude-compatible subagent definition
• mapped instructions from agent.md
• skill projections where applicable
• MCP wiring and install hints

Codex adapter

Could generate or install:

• harness-specific agent definitions or config
• mapped instructions and capability declarations
• projected script exposure
• structured output config when present

Cursor adapter

Could generate or install:

• project rules/context files
• MCP configuration
• invocation scaffolding
• references to packaged assets

Installer responsibilities

A future npx dotagent-pack utility should support at least:

• install
• validate
• pack
• unpack
• list
• inspect
• upgrade
• uninstall

install

Expected behavior:

• read agent.yaml
• validate package shape
• copy, link, or register assets as needed
• run adapter logic for the target runtime
• record lifecycle state in a local registry
• report unsupported features and degraded mappings

validate

Expected behavior:

• check manifest correctness
• verify entrypoints and bundled asset paths
• verify schema references if present
• verify adapter compatibility declarations

pack

Expected behavior:

• convert a folder-first package into a distributable .agent archive

upgrade

Expected behavior:

• compare installed registry state versus package source
• re-run adapter install steps safely

uninstall

Expected behavior:

• remove runtime projections created by the installer
• update the local registry
• avoid deleting unrelated user-authored files

Local registry

The installer should maintain a local registry of installed packages.

Possible responsibilities:

• package id and version tracking
• install timestamps
• source path or archive provenance
• target runtime install records
• generated file projections
• upgrade/uninstall bookkeeping

This registry should support package lifecycle without becoming the package source of truth.

Safety and trust model

Because packages may include scripts and runtime adaptation logic, the standard will need an explicit trust model.

Likely v0 principles:

• executable assets must be declared in the manifest
• adapters must be explicit about what gets exposed into a runtime
• validation should surface potentially risky package behavior
• lifecycle actions should be inspectable

Comparison to Claude-style single-file subagents

Claude’s subagent markdown format is an important inspiration, but it should not be the entire package model.

Why not use only agent.md frontmatter?

• package-manager concerns grow quickly: install, validate, upgrade, uninstall, pack
• multi-runtime adapter metadata does not fit cleanly into behavioral markdown
• bundled assets, projections, and lifecycle state are clearer in a dedicated manifest

Recommended split:

• agent.md for behavior
• agent.yaml for package metadata and installer semantics

Open questions

• Should .agent archives be zip-based, tar-based, or another container?
• How should secrets requirements be declared?
• How should runtime capability degradation be reported?
• How should package signatures or checksums work later?
• How should nested dependencies and packaged skill versions be pinned?
• Should v0 define a minimal runtime compatibility profile?

v0 deliverables

Near-term spec work should produce:

1. a formal agent.yaml schema draft
2. a required directory layout for folder-first packages
3. a behavior contract for agent.md
4. adapter mapping rules for Claude, Codex, and Cursor
5. a local registry model for the installer
6. CLI command semantics for npx dotagent-pack
7. at least three reference example packages

Working summary

dotagent-pack is currently oriented around this v0 thesis:

• build a folder-first portable subagent package
• represent the package with agent.yaml plus agent.md
• allow skills, MCP declarations, scripts, templates, and examples
• keep schemas optional
• generate runtime-native installs through adapters
• manage lifecycle through an npx installer with a local registry

In short: the .agent package should represent a portable specialist capability bundle, and npx dotagent-pack should install that bundle into the target agent runtime.