satchel-agent 0.1.0

Product-agnostic build tooling for agent plugin packages.

Satchel

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

Quick Start | Features | Usage | Release Readiness

Status: public alpha candidate. Satchel can generate and check Codex, Claude, and GitHub Copilot plugin manifests and marketplace files today. Antigravity output is available as an experimental target while its host install flow stabilizes.

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

git clone https://github.com/parkerhancock/satchel.git
cd satchel
uv run satchel init my-plugin
uv run satchel generate my-plugin
uv run satchel check my-plugin
uv run 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

Feature	What it does
Neutral manifest	Reads satchel.yaml as the package source of truth.
Target adapters	Emits deterministic Codex, Claude, Copilot, and experimental Antigravity outputs through pluggable adapters.
Drift checks	Fails when generated outputs are missing or stale.
Smoke tests	Copies a package to a temporary directory, regenerates output, and validates the clean copy.
Host validation	Runs non-mutating host validators where available, including claude plugin validate.
Path safety	Rejects component and output paths that escape the package root.
Skill validation	Checks each skill directory for SKILL.md, name, and description.
Fixture suite	Exercises skills-only, MCP, target-rich, Antigravity, and unsupported-target packages.
Portability report	Summarizes target support and shared components.

Usage

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 a clean-copy smoke test:

uv run satchel smoke my-plugin

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

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

Output Model

Source	Codex	Claude	Copilot	Antigravity
name, version, description	.codex-plugin/plugin.json	.claude-plugin/plugin.json	.github/plugin/plugin.json	plugin.json in the generated package root
components.skills.path	skills field	skills field	skills field	copied to skills/
components.mcp.path	mcpServers field	default .mcp.json	mcpServers field	copied to mcp_config.json
components.hooks.path	hooks field	default hooks/hooks.json	hooks field	copied to hooks.json
targets.codex.interface	interface object	not emitted	not emitted	not emitted
targets.claude.displayName	not emitted	displayName	not emitted	not emitted
target marketplace config	.agents/plugins/marketplace.json	.claude-plugin/marketplace.json	.github/plugin/marketplace.json	not supported yet

Generated manifests should be treated as build outputs. Edit satchel.yaml instead.

Commands

Command	Purpose
satchel init <path>	Create a minimal package with satchel.yaml and one skill.
satchel generate <path>	Generate enabled host manifests.
satchel check <path>	Validate source and fail on stale generated files.
satchel check <path> --host	Add non-mutating host validators when available.
satchel smoke <path>	Validate a regenerated temporary copy without mutating the source tree.
satchel report <path>	Print a simple portability report.

Release Readiness

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

Area	Status
Host validation	satchel check --host runs claude plugin validate when available and structural validators for generated Codex, Claude, Copilot, and Antigravity outputs.
Clean smoke tests	satchel smoke regenerates and validates a temporary package copy.
CI	.github/workflows/ci.yml runs lint, tests, satchel check, and satchel smoke.
Packaging	pyproject.toml has public package metadata and .github/workflows/publish.yml supports trusted PyPI publishing from GitHub releases.
Project hygiene	CONTRIBUTING.md, SECURITY.md, ROADMAP.md, and issue templates are present.
Schema docs	docs/schema.md and schemas/satchel.schema.json document the manifest.
Fixtures	fixtures/ covers skills-only, skills-and-MCP, Claude-rich, Codex-rich, Copilot-rich, Antigravity-rich, and unsupported-target packages.
Demo	examples/release-auditor/ is a non-trivial generated multi-target plugin.

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:

• generated marketplace patch mode
• satchel pack --target codex|claude|copilot|antigravity
• satchel smoke --target codex|claude|copilot|antigravity
• optional plugin-scanner verify integration
• generated docs from schemas/satchel.schema.json

Development

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

License

Satchel is released under the MIT License.