# How Ponytail Ensures Agent Portability: A Complete Technical Guide

> Discover how Ponytail ensures agent portability by separating logic from adapters and offering a universal instruction set for LLM agents. Read the technical guide.

- Repository: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
- Tags: how-to-guide
- Published: 2026-09-06

---

**Ponytail ensures agent portability by cleanly separating core skill logic from host-specific adapters and exposing a tiny, universal instruction set that any LLM-agent can consume.**

Agent portability—the ability to run the same capabilities across Claude, Codex, OpenCode, Hermes, and dozens of other LLM-agent platforms—is a major engineering challenge in the AI tooling space. Ponytail, an open-source "lazy senior dev" assistant, solves this through a strict architectural separation between **portable skills** and **thin host adapters**. This article breaks down exactly how the `DietrichGebert/ponytail` repository implements this design, with direct references to source files and the specific mechanisms that make cross-platform deployment trivial.

## Core Skills: Platform-Agnostic Logic in `skills/`

All functional behavior in Ponytail lives in the `skills/` directory, completely decoupled from any host platform.

The primary skill definition resides at [`skills/ponytail/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail/SKILL.md). This file contains pure, language-model-driven instructions that define Ponytail's six core commands:

- `/ponytail` — Generate or refine code
- `/ponytail-review` — Review changes
- `/ponytail-audit` — Audit for issues
- `/ponytail-debt` — Identify technical debt
- `/ponytail-gain` — Suggest improvements
- `/ponytail-help` — Show available commands

Because these skills are expressed as **markdown instructions** rather than code, they require no compilation, no runtime dependencies, and no host-specific APIs. Any LLM that can read a file can execute the behavior.

## Thin Adapters: Minimal Host-Specific Wrappers

For each supported host platform, Ponytail ships a minimal adapter that merely **points to the shared skill files** and, when necessary, adds a small hook or manifest.

According to [`docs/agent-portability.md`](https://github.com/DietrichGebert/ponytail/blob/main/docs/agent-portability.md), current adapters include:

| Host | Adapter Location | Mechanism |
|------|------------------|-----------|
| Claude | [`.claude-plugin/plugin.json`](https://github.com/DietrichGebert/ponytail/blob/main/.claude-plugin/plugin.json) | Plugin manifest referencing `skills/` |
| Codex | [`.codex-plugin/plugin.json`](https://github.com/DietrichGebert/ponytail/blob/main/.codex-plugin/plugin.json) | Extension manifest with skill path |
| OpenCode | `.opencode/hooks/` | Hook-based integration |
| Hermes | Host-native config | Direct skill file reference |
| JetBrains Junie | Project-level config | [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) fallback |
| VS Code | Various extension formats | Mixed adapter strategies |

The critical rule: **adapters never duplicate skill logic**. They only translate the host's plugin/extension format into references to the shared `skills/` and `hooks/` directories.

### Example: Claude Plugin Adapter

```json
// .claude-plugin/plugin.json
{
  "name": "ponytail",
  "skills": ["skills/ponytail/"],
  "hooks": ["hooks/"]
}

```

This manifest is the *entire* host-specific code for Claude support. The adapter imports the shared skill directory; no Python or JavaScript implementation code is required.

## The Adapter Rule: Enforcing Portability Discipline

Ponytail's architecture is governed by what the repository calls the **Adapter Rule**, documented in [`docs/agent-portability.md`](https://github.com/DietrichGebert/ponytail/blob/main/docs/agent-portability.md). This rule mandates that adapters stay thin through a strict two-path system:

1. **When a host supports skills or hooks** — The adapter points directly to `skills/` and `hooks/`. The host loads and executes the portable skill definitions.

2. **When a host only reads project instructions** — The adapter copies the relevant text from [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) into the host's native instruction format.

This discipline guarantees that adding a new host requires **only a small manifest file**, never a rewrite of core logic. The same six Ponytail commands behave identically whether invoked through a sophisticated plugin system or a simple text-instruction interface.

## [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md): The Universal Fallback

For agents that cannot load separate skill files—generic LLM agents, Zed, Amp, and similar—Ponytail provides [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md), a compact rule set encoding all six commands in a single markdown-compatible block.

This file enables **zero-install portability**. Any agent that reads project instructions automatically receives Ponytail's behavior without host-specific configuration. The [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) fallback ensures that even unsupported or future platforms can use Ponytail's capabilities immediately.

Example excerpt from [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md):

```markdown
When the user types a command starting with `/ponytail`, interpret it as follows...

/ponytail [mode] — Generate code using the "lazy senior dev" persona...

```

## Unified Command Set: Consistent Experience Everywhere

Agent portability fails when command syntax varies by platform. Ponytail eliminates this friction through a **unified command set** defined in the skill files.

Every host adapter maps the same command names to the same core logic:

```text
/ponytail full        # Generate complete implementation

/ponytail-review      # Review current changes

/ponytail-audit       # Audit codebase for issues

/ponytail-debt        # Flag technical debt

/ponytail-gain        # Suggest high-value improvements

/ponytail-help        # Show command reference

```

Because the interface is **command-prefix based** rather than API-based, users enjoy identical experiences across CLIs, IDEs, and chat interfaces. The adapter's only job is recognizing `/ponytail` and routing to the appropriate skill implementation.

## Portable Hooks: Optional Lifecycle Integration

The `hooks/` directory contains optional lifecycle hooks (JSON definitions) used by hosts that support pre-action and post-action events. Like skills, these are:

- Defined once in `hooks/`
- Referenced by adapters, not embedded in them
- Completely optional—hosts without hook support simply ignore them

This extends portability to **behavioral customization** without fragmenting the implementation across host-specific codebases.

## Architecture Comparison: Ponytail vs. Traditional Agent Tools

| Aspect | Traditional Approach | Ponytail's Portable Approach |
|--------|---------------------|------------------------------|
| Skill logic | Embedded in host-specific code | Defined once in `skills/` |
| New host support | Rewrite or fork required | Manifest file only |
| Command consistency | Varies by platform | Unified `/ponytail` prefix |
| Fallback behavior | None | [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) universal support |
| Maintenance burden | O(N) per host | O(1) core + O(1) per adapter |

## Adding a New Host: Step-by-Step

To demonstrate how Ponytail's portability architecture works in practice, here's the complete process for adding "MyAgent" support:

1. Create [`myagent-plugin.json`](https://github.com/DietrichGebert/ponytail/blob/main/myagent-plugin.json):

```json
{
  "name": "ponytail",
  "skills": ["skills/ponytail/"],
  "hooks": ["hooks/"]
}

```

2. Place in host-expected location (e.g., [`.myagent/plugin.json`](https://github.com/DietrichGebert/ponytail/blob/main/.myagent/plugin.json))

3. Done. No logic changes. No code review of skill behavior.

If MyAgent doesn't support plugins, instead create a one-line config pointing to [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) or inline its contents.

## Summary

- **Core skills** live in [`skills/ponytail/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail/SKILL.md) as portable, LLM-executable instructions
- **Thin adapters** in host-specific formats only reference shared skills, never duplicate logic
- **The Adapter Rule** enforces strict separation between portable and host-specific concerns
- **[`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md)** provides universal fallback for agents without skill-loading capabilities
- **Unified command syntax** (`/ponytail`, `/ponytail-review`, etc.) ensures consistent UX across all platforms
- **Optional hooks** in `hooks/` extend functionality without compromising portability

## Frequently Asked Questions

### What makes Ponytail's approach different from other multi-platform agent tools?

Most tools embed platform-specific logic in each adapter or use conditional compilation. Ponytail inverts this: **skills are the source of truth**, and adapters are trivial manifests. This means a bug fix in [`skills/ponytail/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail/SKILL.md) immediately propagates to every supported host without individual adapter updates.

### Can I use Ponytail with an LLM agent that isn't officially supported?

Yes. Any agent that reads project files will automatically pick up [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md). Simply ensure your agent processes instructions from repository markdown files, and the `/ponytail` command set becomes available without any host-specific configuration. This is how platforms like Zed and Amp gain Ponytail functionality without dedicated adapters.

### How does Ponytail handle platform-specific capabilities like tool use or custom renderers?

Ponytail deliberately avoids these. The **instruction-only** design assumes the LLM itself is the execution engine. When hosts support additional capabilities—Claude's artifacts, VS Code's webviews—adapters may add thin presentation layers, but the core skill logic in `skills/` remains unchanged. The `hooks/` directory provides lifecycle integration points without requiring skill modifications.

### What's the maintenance burden when adding support for a new host platform?

Minimal. Based on the patterns in [`docs/agent-portability.md`](https://github.com/DietrichGebert/ponytail/blob/main/docs/agent-portability.md), new host support typically requires:
- One JSON manifest file (2–10 lines)
- Optional: One-line reference to [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) if the host lacks skill-loading
- No changes to `skills/`, `hooks/`, or command definitions

Reported effort in the repository: **under 30 minutes** for hosts with documented plugin formats.