Satchel

Satchel lets agent plugin authors build multi-target extensions from one source package.

Quick Start | Features | Usage | Release Readiness

Status: public alpha. Satchel can generate and check Codex, Claude, and GitHub Copilot plugin manifests and marketplace files today. ChatGPT app and Anthropic Connectors Directory release artifacts are available as metadata/checklist targets. Antigravity output is available as an experimental target while its host install flow stabilizes.

Note: the claude target builds a Claude Code plugin; the anthropic target builds an Anthropic Connectors Directory submission (a remote MCP server listing). They are different distribution channels.

Why Satchel

Modern agent plugins share useful building blocks: skills, SKILL.md metadata, supporting files, MCP configuration, hooks, and subagent definitions. Their manifests and marketplace catalogs are different enough that multi-target plugin repos can drift.

Satchel makes satchel.yaml the source of truth. Authors edit one portable package, then generate host-specific files and fail CI when generated outputs are stale.

Quick Start

uvx --from satchel-agent satchel init my-plugin
uvx --from satchel-agent satchel generate my-plugin
uvx --from satchel-agent satchel check my-plugin
uvx --from satchel-agent satchel smoke my-plugin

The generated files live at:

my-plugin/.codex-plugin/plugin.json
my-plugin/.claude-plugin/plugin.json
my-plugin/.github/plugin/plugin.json
my-plugin/.github/plugin/marketplace.json

Plugin Install

Satchel is packaged with Satchel. The repository root contains satchel.yaml, the generated host manifests, generated marketplace files, and a shared skills/satchel/SKILL.md.

Claude Code:

claude plugin marketplace add parkerhancock/satchel
claude plugin install satchel@satchel-marketplace

Codex:

codex plugin marketplace add parkerhancock/satchel

Then restart Codex, open the plugin directory, choose the Satchel marketplace, and install the Satchel plugin. Codex can also read the generated repo marketplace at .agents/plugins/marketplace.json, which points back to the Git-backed Satchel plugin source.

GitHub Copilot CLI:

copilot plugin marketplace add parkerhancock/satchel
copilot plugin install satchel@satchel-marketplace

Antigravity support is experimental. The adapter can generate a local package layout under .agents/plugins/, but install and marketplace behavior should be verified against the current Antigravity CLI or IDE before relying on it.

Features

Usage

Install from PyPI:

uv tool install satchel-agent
satchel --version

For one-off use without installing:

uvx --from satchel-agent satchel --help

Create a package:

uv run satchel init my-plugin

Generate host manifests:

uv run satchel generate my-plugin

Check source validity and generated-file drift:

uv run satchel check my-plugin

Run host-aware validation when the host CLIs are installed:

uv run satchel check my-plugin --host

Run release installability checks before publishing:

uv run satchel check my-plugin --release

Write machine-readable diagnostics:

uv run satchel check my-plugin --json

See docs/diagnostics.md for diagnostic codes and remediation guidance. See docs/marketplaces.md for marketplace installability workflows. See docs/host-validators.md for host validator behavior.

Run a clean-copy smoke test:

uv run satchel smoke my-plugin
uv run satchel smoke my-plugin --target claude

Build a target-specific archive without mutating the source tree:

uv run satchel pack my-plugin --target claude --release

Print a portability report:

uv run satchel report my-plugin

Manifest

Minimal satchel.yaml:

schema: satchel/v0
name: my-plugin
version: 0.1.0
description: Shared agent extension.
author:
  name: Your Team

components:
  skills:
    path: ./skills
  mcp:
    path: ./.mcp.json

targets:
  codex:
    enabled: true
    manifest: ./.codex-plugin/plugin.json
    interface:
      displayName: My Plugin
      shortDescription: Shared agent extension.
      category: Productivity
      capabilities:
        - Read

  claude:
    enabled: true
    manifest: ./.claude-plugin/plugin.json
    displayName: My Plugin

  copilot:
    enabled: true
    manifest: ./.github/plugin/plugin.json
    marketplace:
      path: ./.github/plugin/marketplace.json
      patch: true

  antigravity:
    enabled: false
    experimental: true
    output: ./.agents/plugins/my-plugin

  chatgpt:
    enabled: false
    manifest: ./chatgpt/app.json
    app:
      displayName: My App
      shortDescription: Shared agent extension.
      mcpUrl: https://example.com/mcp
      privacyUrl: https://example.com/privacy
      termsUrl: https://example.com/terms
      supportUrl: https://example.com/support
    compatibility:
      requireReadOnlyHints: true
      requireSearchFetch: false

Output Model

Generated manifests should be treated as build outputs. Edit satchel.yaml instead. If a marketplace file must retain host-owned fields, set targets.<target>.marketplace.patch: true; Satchel will update the generated plugin entry while preserving unrelated plugin entries and unknown metadata.

Commands

Release Readiness

The repo now includes the release-readiness pieces needed for a public alpha:

Operational release steps are documented in docs/release.md: configure PyPI trusted publishing, cut a GitHub release, then verify uv tool install satchel-agent or pipx install satchel-agent after publishing. The installed CLI command is still satchel.

Good follow-up work after public alpha:

• optional plugin-scanner verify integration
• concrete host validators as more CLIs expose non-mutating plugin validation

Development

uv run ruff check .
uv run pytest
uv run satchel check .
uv run satchel smoke .
uv run satchel standards check .
uv run satchel report examples/basic

License

Satchel is released under the MIT License.