How Ponytail Ensures Agent Portability: A Complete Technical Guide

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. 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, current adapters include:

Host	Adapter Location	Mechanism
Claude	.claude-plugin/plugin.json	Plugin manifest referencing skills/
Codex	.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 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

// .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. 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 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: The Universal Fallback

For agents that cannot load separate skill files—generic LLM agents, Zed, Amp, and similar—Ponytail provides 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 fallback ensures that even unsupported or future platforms can use Ponytail's capabilities immediately.

Example excerpt from AGENTS.md:

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:

/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 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:

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

2. Place in host-expected location (e.g., .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 or inline its contents.

Summary

• Core skills live in 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 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 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. 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, new host support typically requires:

• One JSON manifest file (2–10 lines)
• Optional: One-line reference to 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}