Where to Find Ponytail Agent Portability Documentation: Complete Guide

The Ponytail agent portability documentation lives at docs/agent-portability.md in the DietrichGebert/ponytail repository, with supplementary configuration files in AGENTS.md and the skills/ directory defining how the tool adapts to over 20 different AI agents.

The DietrichGebert/ponytail project implements a cross-platform code review system designed to run consistently across diverse AI development environments. The Ponytail agent portability documentation establishes the architectural patterns that allow the same lazy senior-dev skill set to function identically whether invoked through Claude, Cursor, or JetBrains Junie. This guide explains the exact file locations, adapter rules, and implementation patterns required to deploy Ponytail skills universally.

Location of the Primary Documentation

The definitive source for agent portability rules resides at docs/agent-portability.md in the repository root. This markdown file serves as the canonical reference for adapter implementation, detailing how to bridge Ponytail's core capabilities with specific host requirements. According to the DietrichGebert/ponytail source code, this document specifies the exact file paths and directory structures that each supported agent must reference to access the six core skills: ponytail, ponytail-review, ponytail-audit, ponytail-debt, ponytail-gain, and ponytail-help.

The Adapter Rule and Architecture

The portability documentation establishes a strict Adapter Rule to minimize code duplication across environments. Hosts must keep adapters thin by pointing directly at the existing skills/ and hooks/ directories whenever possible. For agents that only accept project-level instruction files rather than directory-based skill loading, the system falls back to AGENTS.md, a compact always-on instruction set that consolidates the essential behaviors without requiring the full directory structure.

This architectural approach ensures that behavior updates propagate automatically across all supported platforms. When the maintainers update the logic in skills/ponytail/SKILL.md, every adapter referencing that file receives the changes immediately without requiring individual plugin updates.

Core Files and Directory Structure

Understanding the relationship between the portability guide and the implementation files is critical for proper deployment:

• docs/agent-portability.md – The primary guide defining adapter requirements and host-specific integration patterns.
• AGENTS.md – A compressed rule file for hosts that cannot load directory-based skills, providing always-on instructions suitable for project-level configuration.
• skills/ponytail/SKILL.md – The lazy senior-dev mode implementation containing the core refactoring logic.
• skills/ponytail-review/SKILL.md – Specialized over-engineering detection and review capabilities.
• skills/ponytail-audit/SKILL.md – Whole-repository audit functionality.
• hooks/claude-codex-hooks.json – Lifecycle hook definitions for hosts supporting event-based integration, such as Claude and Codex.

Supported Agents and Hosts

The Ponytail agent portability documentation explicitly validates compatibility with the following environments:

• Anthropic ecosystem: Claude and Codex (with dedicated hook support in hooks/claude-codex-hooks.json)
• IDE-integrated agents: Cursor, Windsurf, Cline, VS Code + Codex, JetBrains Junie, Zed
• CLI tools: Gemini CLI, GitHub Copilot CLI, Grok, OpenCode, pi
• Specialized platforms: Hermes, Antigravity, CodeWhale, Swival, Amp, Jules, Kiro, Qoder
• Generic agents: Standard pattern for unsupported hosts following the adapter specification

Each entry in docs/agent-portability.md specifies whether the host requires the full directory structure (pointing to skills/ and hooks/) or operates exclusively through AGENTS.md.

Implementation Examples

The following patterns demonstrate how to load Ponytail skills according to the portability specifications:

Loading Skills Programmatically

For generic agents or custom integrations, import skills directly from the repository structure:

import importlib.util
import pathlib

# Locate the repository root

repo_root = pathlib.Path(__file__).parent.parent
skills_path = repo_root / "skills" / "ponytail"

# Load the skill module dynamically

spec = importlib.util.spec_from_file_location(
    "ponytail_skill", 
    skills_path / "SKILL.md"
)
ponytail = importlib.util.module_from_spec(spec)
spec.loader.exec_module(ponytail)

# Execute a specific command

result = ponytail.run({"command": "/ponytail-help"})
print(result)

Grok Plugin Installation

For the Grok Build host, use the official plugin manager:

# Install from the repository

grok plugin install DietrichGebert/ponytail --trust

# Enable the adapter

grok plugin enable ponytail

OpenCode Manifest Declaration

For OpenCode compatibility, declare the plugin entry point in your project configuration:

[plugin]
name = "ponytail"
entry = ".opencode/plugins/ponytail.mjs"

Summary

• Primary documentation: docs/agent-portability.md contains the complete adapter specification and host requirements.
• Fallback configuration: AGENTS.md provides compact, always-on instructions for agents limited to project-level rules.
• Adapter philosophy: Keep host-specific code minimal by referencing the canonical skills/ and hooks/ directories directly.
• Universal compatibility: The system supports 20+ agents including Claude, Cursor, Grok, OpenCode, JetBrains Junie, and Zed through standardized patterns.
• Core skills: Six portable behaviors (ponytail, ponytail-review, ponytail-audit, ponytail-debt, ponytail-gain, ponytail-help) defined in individual SKILL.md files.

Frequently Asked Questions

Where exactly is the Ponytail agent portability documentation located?

The documentation is located at docs/agent-portability.md in the DietrichGebert/ponytail repository. This file provides the authoritative specification for adapter implementation and lists every supported AI agent platform along with their specific integration requirements.

What is the difference between docs/agent-portability.md and AGENTS.md?

docs/agent-portability.md is the comprehensive guide explaining how to build adapters for different hosts and details the full directory-based architecture. AGENTS.md serves as a compressed, stand-alone instruction set used by hosts that only support project-level configuration files and cannot reference external skills/ directories directly.

Which AI agents are supported by the Ponytail portability system?

The system officially supports Claude, Codex, Grok, OpenCode, pi, Hermes, Gemini CLI, Cursor, Windsurf, Cline, GitHub Copilot, Antigravity, CodeWhale, Swival, VS Code + Codex, JetBrains Junie, Amp, Jules, Kiro, Qoder, Zed, and generic agents through documented adapter patterns. Each adapter points either to the full skills/ directory structure or to the compact AGENTS.md file depending on host capabilities.

How do I install Ponytail on agents like Grok or OpenCode?

For Grok, run grok plugin install DietrichGebert/ponytail --trust followed by grok plugin enable ponytail. For OpenCode, add the plugin manifest entry to your configuration file pointing to entry = ".opencode/plugins/ponytail.mjs". Agents supporting generic patterns can load skills directly by importing the SKILL.md files from skills/ponytail/ and related subdirectories.

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