From 784e8bfd1c1acbac90ee6367340f3e627e22fc2f Mon Sep 17 00:00:00 2001 From: Chindanai Jaiman Date: Fri, 12 Jun 2026 22:39:15 +0700 Subject: [PATCH] Document agent adapters (#2) --- docs/agent-portability.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 docs/agent-portability.md diff --git a/docs/agent-portability.md b/docs/agent-portability.md new file mode 100644 index 0000000..7412d0f --- /dev/null +++ b/docs/agent-portability.md @@ -0,0 +1,31 @@ +# Agent Portability + +Ponytail is an agent-portable skill distribution. The skills in `skills/` hold +the core behavior; host-specific files are adapters that make that behavior easy +to load in a given agent. + +## Supported Adapters + +| Host | Files | Notes | +|------|-------|-------| +| Claude Code | `.claude-plugin/`, `commands/`, `hooks/` | Full plugin install with session activation, mode tracking, commands, and statusline support. | +| Codex | `.codex-plugin/plugin.json`, `hooks/hooks.json`, `hooks/`, `skills/` | Plugin install with the same skills plus lifecycle hooks for activation and mode tracking. | +| Cursor | `.cursor/rules/ponytail.mdc` | Always-on project rule. | +| Windsurf | `.windsurf/rules/ponytail.md` | Project rule. | +| Cline | `.clinerules/ponytail.md` | Project rule. | +| GitHub Copilot | `.github/copilot-instructions.md` | Repository instruction file. | +| Kiro | `.kiro/steering/ponytail.md` | Steering rule; copy globally or into a project. | +| Generic agents | `AGENTS.md` or `skills/*/SKILL.md` | Copy the compact rule file or load the skill files directly. | + +## Adapter Rule + +Keep adapters thin. When a host supports skills or hooks, point it at the +existing `skills/` and `hooks/` files. When a host only supports project +instructions, keep its copied rule text aligned with `AGENTS.md`. + +## Portable Behavior + +- `skills/ponytail/SKILL.md`: lazy senior dev mode +- `skills/ponytail-review/SKILL.md`: over-engineering review +- `skills/ponytail-help/SKILL.md`: quick reference +- `AGENTS.md`: compact always-on instruction set for agents without skill support