Caddie

Caddie is an agent-first manager for skills across user and project scopes, made available to multiple agent harnesses.

It is designed to give an agent a bird's-eye view of a user's skill environment: where skills come from, which exact revisions are selected, what is installed, what has drifted, and which projects need attention. Caddie combines a conversational agent skill with deterministic tooling for inspection, reconciliation, and safe change planning.

Status

Caddie v1 is under active implementation.

• Caddie v1 specification
• First implementation ticket

The specification and its tracer-bullet tickets remain the baseline v1 product requirements. Repository architecture decisions record accepted changes and supersede only the requirements they identify.

Intended experience

• Keep User Skills available across projects.
• Add project-owned capabilities through Project Skills.
• Install User Skills in the cross-client ~/.agents/skills convention and add only the Claude compatibility links that are needed.
• Keep Caddie's User Skills state together in ~/.agents/.caddie; keep each project's state in <project>/.agents/.caddie.
• Select complete skills from local or pinned Git sources.
• Enable or disable a selected skill without uninstalling it, using each harness's native settings.
• Manage user-only invocation consistently across Codex and Claude-compatible metadata without modifying Skill Sources.
• Detect upstream changes, local drift, renames, and derived skill lineage.
• Review an exact plan before Caddie mutates managed state.
• Inspect every registered project from one conversational bird's-eye view.

Caddie is an Agent App. Users interact through the Caddie Skill, which directs the Caddie Tool; bootstrap is the only intended direct shell interaction.

Design principles

• Preserve authored and installed content unless the user explicitly approves its removal.
• Separate deterministic evidence, agent interpretation, user choice, and durable state.
• Store complete User Skills in ~/.agents/skills and complete Project Skills in <project>/.agents/skills; use harness-specific links only for compatibility.
• Recommend Git without requiring it.
• Leave ordinary repository authoring, worktrees, commits, and pull requests to the hosting agent.
• Keep desired state, resolved state, and expensive semantic decisions durable; compute routine reports live.

The v1 specification remains the baseline; see the architecture decisions for accepted changes.

Caddie Tool

The deterministic tool accepts one versioned JSON request on standard input:

printf '%s\n' '{"version":1,"operation":"locate","input":{"cwd":"/path/to/project"}}' | node bin/caddie-tool.mjs

The self-contained Caddie Skill source is in skills/caddie. .agents/skills is reserved for installed User Skills and Project Skills, not source-repository organization. Bootstrap is the only intended human-facing shell action; normal management remains conversational and approval-gated.

Existing v1 installations that stored state under ~/.config/caddie are upgraded through Caddie's explicit, preservation-first state-migration workflow. Migration is inspected, planned, approved, applied, and verified like every other managed-state change; bootstrap does not silently rewrite an existing installation.

See the protocol and persisted formats.

License

MIT