# Ponytail Portable Skill System Architecture: How the Lazy Senior Dev Pattern Works Across AI Agents

> Explore the Ponytail Portable Skill System architecture. Learn how its three-layer design enables consistent lazy senior dev patterns across diverse AI agents like Claude and Codex.

- Repository: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
- Tags: architecture
- Published: 2026-08-29

---

**Ponytail implements a three-layer portable skill distribution that separates declarative core behaviors from host-specific adapters, enabling consistent "lazy senior dev" patterns across Claude, Codex, OpenCode, Hermes, and other LLM agents.**

The **Ponytail Portable Skill System architecture** is a deliberate departure from monolithic AI coding assistants. Developed in the `DietrichGebert/ponytail` repository, this system treats coding assistance as a portable capability that travels with the codebase rather than residing inside a specific IDE or model. By decoupling skill definitions from runtime environments, Ponytail ensures that sophisticated code review, technical debt tracking, and architectural auditing behaviors remain consistent regardless of which AI agent a developer invokes.

## Core Components of the Architecture

The Ponytail Portable Skill System architecture consists of three distinct layers designed to maximize compatibility while minimizing host-specific code.

### Core Skills Layer

The foundation resides in the `skills/` directory, where each capability is defined as a standalone markdown document with front-matter metadata. These files embody the **"lazy senior dev" philosophy**—deliberate minimalism that prioritizes maintainability over cleverness.

Key skill definitions include:
- [`skills/ponytail/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail/SKILL.md) — The base activation skill with intensity levels (lite, full, ultra)
- [`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-review/SKILL.md) — Over-engineering detection and review protocols
- [`skills/ponytail-audit/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-audit/SKILL.md) — Whole-repository architectural auditing
- [`skills/ponytail-debt/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-debt/SKILL.md) — Technical debt ledger management
- [`skills/ponytail-gain/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-gain/SKILL.md) — Performance benchmark tracking
- [`skills/ponytail-help/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-help/SKILL.md) — Quick reference documentation

Each [`SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/SKILL.md) file contains declarative definitions including name, description, intensity ladders, and behavioral constraints. Host agents parse these files to understand available capabilities without executing arbitrary code.

### Adapter Layer

Adapters provide **thin glue code** that translates between Ponytail's declarative skill format and each host agent's native plugin system. The architecture follows the principle of keeping adapters minimal—if a host supports skills or hooks natively, the adapter simply points to the existing `skills/` directory.

Example adapter implementations include:
- [`.claude-plugin/plugin.json`](https://github.com/DietrichGebert/ponytail/blob/main/.claude-plugin/plugin.json) — Claude Desktop integration manifest
- [`.codex-plugin/plugin.json`](https://github.com/DietrichGebert/ponytail/blob/main/.codex-plugin/plugin.json) — OpenAI Codex compatibility layer
- `.opencode/plugins/ponytail.mjs` — OpenCode Node.js runtime plugin
- [`plugin.yaml`](https://github.com/DietrichGebert/ponytail/blob/main/plugin.yaml) — Hermes native plugin descriptor
- [`.grok-plugin/marketplace.json`](https://github.com/DietrichGebert/ponytail/blob/main/.grok-plugin/marketplace.json) — Grok marketplace configuration
- [`.kiro/steering/ponytail.md`](https://github.com/DietrichGebert/ponytail/blob/main/.kiro/steering/ponytail.md) — Kiro steering instructions

These adapters register slash commands (like `/ponytail`, `/ponytail-review`) and inject the appropriate rule sets into the host's system prompt each turn.

### Rule and Instruction Layer

For agents without native skill support, Ponytail provides **always-on text files** that serve as compact instruction sets. These files ensure portability to environments lacking sophisticated plugin architectures.

Critical rule files include:
- [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) — The primary compact rule set readable by any LLM
- [`docs/agent-portability.md`](https://github.com/DietrichGebert/ponytail/blob/main/docs/agent-portability.md) — Comprehensive adapter implementation guide
- `.cursor/rules/ponytail.mdc` — Cursor-specific rule format
- [`.windsurf/rules/ponytail.md`](https://github.com/DietrichGebert/ponytail/blob/main/.windsurf/rules/ponytail.md) — Windsurf IDE integration
- [`.clinerules/ponytail.md`](https://github.com/DietrichGebert/ponytail/blob/main/.clinerules/ponytail.md) — Cline rule set

When an adapter is unavailable, developers can copy these rule files into their project root, allowing the agent to load Ponytail behaviors through standard context window ingestion.

## How the Portable Skill System Works at Runtime

The Ponytail Portable Skill System architecture activates through a specific runtime flow that maintains state across interactions.

### Skill Activation Flow

When a developer invokes `/ponytail full`, the host agent performs the following sequence:

1. **Capability Discovery** — The adapter scans `skills/` for available [`SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/SKILL.md) files and parses their front-matter to build a capability index
2. **Context Injection** — The adapter loads the corresponding rule text (from [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) or the skill definition) and prepends it to the system prompt
3. **Mode Persistence** — The selected intensity level (lite, full, or ultra) persists until explicitly cleared via `/ponytail stop` or host termination
4. **Command Routing** — Slash commands map to specific skill files; `/ponytail-review` triggers [`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-review/SKILL.md) behaviors

### Host Integration Patterns

The architecture supports two primary integration strategies:

**Native Skill Loading** — For hosts like Claude and Codex that support structured skills, the adapter references [`commands/ponytail.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail.toml) to define parameter schemas:

```toml

# commands/ponytail.toml

name = "ponytail"
description = "Activate Ponytail lazy-dev mode"
trigger = "/ponytail"
parameters = [
  { name = "level", type = "string", enum = ["lite","full","ultra"], default = "full" }
]

```

**Transform-Based Injection** — For hosts requiring runtime text transformation, adapters fetch and inject rule content dynamically:

```javascript
// .opencode/plugins/ponytail.mjs
import { registerPlugin } from 'opencode';

registerPlugin('ponytail', {
  transformSystem: async (systemPrompt) => {
    const rules = await fetch('/AGENTS.md').then(r => r.text());
    return `${systemPrompt}\n${rules}`;
  }
});

```

### Fallback Mechanisms

When neither native skills nor plugin APIs are available, the system degrades gracefully. Developers can manually prepend [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) to their context, or copy specific [`SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/SKILL.md) contents into the chat. This ensures the **portable skill distribution** functions even in restricted environments like vanilla ChatGPT or basic API integrations.

## Implementation Examples

The following examples demonstrate how the architecture manifests across different host environments.

### Command Definition for Claude/Codex

Structured command definitions live in the `commands/` directory and map user inputs to skill activations:

```toml

# commands/ponytail-review.toml

name = "ponytail-review"
description = "Review code for over-engineering and unnecessary complexity"
trigger = "/ponytail-review"
required_files = ["skills/ponytail-review/SKILL.md"]
accepted_args = ["file", "snippet"]

```

### OpenCode Runtime Integration

The OpenCode adapter demonstrates dynamic rule injection without static configuration:

```javascript
// Runtime skill loader example
const skillLoader = {
  async loadSkill(skillName) {
    const skillPath = `skills/${skillName}/SKILL.md`;
    const content = await fs.readFile(skillPath, 'utf8');
    return this.parseFrontMatter(content);
  },
  
  injectRules(systemPrompt, intensity = 'full') {
    const baseRules = this.loadAGENTS();
    return `${systemPrompt}\n## Ponytail Mode: ${intensity}\n${baseRules}`;

  }
};

```

### Direct CLI Invocation

For agents reading [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) directly, the system supports conventional command patterns:

```bash

# Activate base Ponytail mode

$ ponytail full

# Run specific skills

$ ponytail review --file ./src/complex-module.js
$ ponytail debt --note "Refactor this legacy pattern later"
$ ponytail audit --scope ./src

```

## Summary

The Ponytail Portable Skill System architecture achieves cross-platform AI agent compatibility through:

- **Declarative skill definitions** in `skills/*/SKILL.md` that describe capabilities independent of runtime environment
- **Minimal host adapters** located in `.claude-plugin/`, `.opencode/plugins/`, and similar directories that bridge Ponytail's markdown-based skills to specific agent APIs
- **Universal rule files** like [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) that ensure fallback functionality for agents without plugin support
- **Intensity-based activation** via `/ponytail lite|full|ultra` commands that persist state across interactions
- **Thin adapter philosophy** ensuring the same logic works whether loaded via native skill APIs or simple text injection

## Frequently Asked Questions

### What makes Ponytail "portable" compared to other AI coding assistants?

Unlike IDE-specific extensions or model-tuned behaviors, Ponytail stores its intelligence in markdown files ([`SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/SKILL.md), [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md)) that travel with your repository. Any agent that can read text files—including Claude, Codex, Cursor, or even basic ChatGPT—can load these skills. The adapters merely optimize the loading mechanism; the core logic remains readable, version-controlled documentation.

### How do the intensity levels (lite, full, ultra) change Ponytail's behavior?

Each [`SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/SKILL.md) file defines a "ladder of laziness" with three enforcement tiers. In `lite` mode, Ponytail makes gentle suggestions about over-engineering. `full` mode enforces strict simplicity constraints and rejects unnecessary abstractions. `ultra` mode applies aggressive minimalism, blocking complex patterns unless explicitly justified. The adapter stores the selected level in conversation state until `/ponytail stop` clears it.

### Can I use Ponytail with an AI agent that isn't listed in the adapters?

Yes. The **portable skill distribution** design specifically accommodates unknown agents. Copy the contents of [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) into your system prompt or project context. For specific capabilities, paste the relevant `skills/ponytail-*/SKILL.md` content. The [`docs/agent-portability.md`](https://github.com/DietrichGebert/ponytail/blob/main/docs/agent-portability.md) file provides guidelines for writing new adapters if you need deeper integration.

### Where should I look to understand how to build a new adapter for my specific tool?

The canonical reference is [`docs/agent-portability.md`](https://github.com/DietrichGebert/ponytail/blob/main/docs/agent-portability.md), which details the interface between skill files and host agents. Examine `.opencode/plugins/ponytail.mjs` for a JavaScript runtime example, or [`.claude-plugin/plugin.json`](https://github.com/DietrichGebert/ponytail/blob/main/.claude-plugin/plugin.json) for a declarative manifest approach. The key requirement is parsing the front-matter from `skills/` markdown files and injecting the rule text into the agent's context window.