# How the Plugin Tier in Ponytail Differs from the Instruction-Only Tier

> Explore the Ponytail plugin tier vs instruction-only tier. Discover how plugins enable dynamic switching, skill registration, and automation for enhanced agent capabilities.

- Repository: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
- Tags: deep-dive
- Published: 2026-09-11

---

**The plugin tier installs host-specific manifests and hooks that enable dynamic mode switching, skill registration, and lifecycle automation, whereas the instruction-only tier relies solely on static AGENTS.md files without interactive commands or state management.**

Ponytail supports two distinct integration patterns for AI coding assistants. Understanding how the **plugin tier** differs from the **instruction-only tier** helps developers choose the right deployment strategy for their workflow. This article examines the architectural distinctions, file structures, and runtime behaviors defined in the DietrichGebert/ponytail repository.

## Installation and File Structure

The **plugin tier** requires host-specific plugin manifests and runtime hooks. According to the agent-portability documentation, this includes files such as [`.claude-plugin/plugin.json`](https://github.com/DietrichGebert/ponytail/blob/main/.claude-plugin/plugin.json), [`.codex-plugin/plugin.json`](https://github.com/DietrichGebert/ponytail/blob/main/.codex-plugin/plugin.json), `.opencode/plugins/ponytail.mjs`, and activation hooks in [`hooks/ponytail-activate.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-activate.js). These files enable the host to load Ponytail as a first-class plugin with full lifecycle support.

The **instruction-only tier** requires no additional files beyond a plain-text instruction file. As noted in the README, the repository uses [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) as an instruction-only fallback when the plugin is absent. Some hosts also recognize [`.github/copilot-instructions.md`](https://github.com/DietrichGebert/ponytail/blob/main/.github/copilot-instructions.md) or similar paths.

## Runtime Capabilities

### Mode Switching and State Management

The plugin tier provides explicit `/ponytail-*` commands that toggle active modes (e.g., `ponytail-review`, `ponytail-audit`). The implementation tracks the current mode using a hidden state file (`.ponytail-active`) and updates a status-line badge dynamically. This stateful management is handled in [`hooks/ponytail-activate.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-activate.js).

The instruction-only tier offers no mode-switching capability. The host reads the static instructions from [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) once at startup and applies them consistently throughout the session without runtime modification.

### Lifecycle Hooks

Plugin tier implementations register **SessionStart**, **SessionEnd**, and **PreToolUse** hooks that inject the ruleset each turn and manage activation states. These hooks are defined in files such as [`hooks/ponytail-activate.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-activate.js) and [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js).

The instruction-only tier executes no hooks. The host simply parses the markdown instructions without triggering custom lifecycle events.

### Skill Exposure

In the plugin tier, Ponytail exposes six built-in skills under the `ponytail:` namespace (e.g., `ponytail:review`, `ponytail:debt`). These are real skill objects that can be invoked using host-specific syntax such as `@ponytail-review`.

The instruction-only tier does not register skills. The [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) file contains only plain text prompts, meaning the host cannot call discrete Ponytail skills as separate functions.

### Per-Project Customization

Plugin installations may ship per-project rule files (e.g., [`.qoder/rules/ponytail.md`](https://github.com/DietrichGebert/ponytail/blob/main/.qoder/rules/ponytail.md)) and can be installed locally to a specific repository without affecting global settings. This allows different projects to maintain different Ponytail configurations simultaneously.

The instruction-only tier typically works globally unless the user creates a project-specific [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) in the repository root. There is no mechanism for project-scoped plugin isolation.

### Update Mechanism

Plugins support automatic updates via host marketplaces (e.g., `copilot plugin marketplace update ponytail`). The [`skills/ponytail-help/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-help/SKILL.md) file documents how to enable auto-update for the plugin tier.

Updating the instruction-only tier requires manually editing the [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) file. There is no versioning or automatic distribution mechanism.

## Code Examples

### Activating the Plugin Tier

When using the plugin tier in Claude Code or similar hosts, you can activate specific modes programmatically:

```javascript
// Activate ponytail in review mode using the plugin command
// The plugin injects the ruleset and tracks the active mode
await ponytail.activate({ mode: "review" });

// Run a ponytail skill directly via the registered namespace
await ponytail.runSkill("ponytail:review", { 
  prompt: "Please critique my PR." 
});

```

The plugin automatically updates the status-line badge and persists the active state to `.ponytail-active`.

### Using the Instruction-Only Tier

With the instruction-only tier, interaction relies entirely on the static context file:

```bash

# No explicit activation required—the host reads AGENTS.md automatically

# Invoke Ponytail-style prompts directly in the chat

"Please write an efficient debounce function in JavaScript."

```

All behavior is derived from the static text in [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md); no state tracking or skill invocation occurs.

### Switching Modes in the Plugin Tier

```javascript
// Toggle to audit mode
await ponytail.switchMode("audit");

// Revert to default mode
await ponytail.switchMode("default");

```

### Customizing Rules for Instruction-Only Deployment

Create a project-specific [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) file:

```markdown

# Custom ponytail rules for this project

@assistant Please follow these style guidelines when generating code:
- Use 2-space indentation.
- Prefer functional components over class components.

```

Place this file in the repository root for the host to load automatically.

## Key Implementation Files

| File | Role | Source Link |
|------|------|-------------|
| [`docs/agent-portability.md`](https://github.com/DietrichGebert/ponytail/blob/main/docs/agent-portability.md) | Defines host-specific plugin layouts and distinguishes full installs from fallback instruction-only paths | [View on GitHub](https://github.com/DietrichGebert/ponytail/blob/main/docs/agent-portability.md) |
| [`README.md`](https://github.com/DietrichGebert/ponytail/blob/main/README.md) | Documents the [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) instruction-only fallback mechanism | [View on GitHub](https://github.com/DietrichGebert/ponytail/blob/main/README.md) |
| [`.claude-plugin/plugin.json`](https://github.com/DietrichGebert/ponytail/blob/main/.claude-plugin/plugin.json) | Claude Code plugin manifest for the full plugin tier | [View on GitHub](https://github.com/DietrichGebert/ponytail/blob/main/.claude-plugin/plugin.json) |
| [`.codex-plugin/plugin.json`](https://github.com/DietrichGebert/ponytail/blob/main/.codex-plugin/plugin.json) | Codex plugin manifest | [View on GitHub](https://github.com/DietrichGebert/ponytail/blob/main/.codex-plugin/plugin.json) |
| `.opencode/plugins/ponytail.mjs` | OpenCode plugin entry point with hook registrations | [View on GitHub](https://github.com/DietrichGebert/ponytail/blob/main/.opencode/plugins/ponytail.mjs) |
| [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) | Instruction-only rules file read by hosts without plugin support | [View on GitHub](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) |
| [`hooks/ponytail-activate.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-activate.js) | Implements SessionStart hooks and state file management | [View on GitHub](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-activate.js) |
| [`skills/ponytail-help/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-help/SKILL.md) | Documents auto-update configuration for plugin installations | [View on GitHub](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-help/SKILL.md) |

## Summary

- The **plugin tier** requires host-specific manifests (e.g., [`.claude-plugin/plugin.json`](https://github.com/DietrichGebert/ponytail/blob/main/.claude-plugin/plugin.json)) and hook files (e.g., [`hooks/ponytail-activate.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-activate.js)), while the **instruction-only tier** needs only [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md).
- Plugin tier provides **mode switching** commands and maintains state in `.ponytail-active`; instruction-only tier uses static, unchanging instructions.
- **Lifecycle hooks** (SessionStart, SessionEnd, PreToolUse) execute only in the plugin tier, enabling dynamic rule injection.
- Registered **skills** under the `ponytail:` namespace are available exclusively in the plugin tier.
- Plugin tier supports **automatic updates** via host marketplaces; instruction-only tier requires manual file editing.

## Frequently Asked Questions

### Can I use both tiers simultaneously in the same project?

No. The host loads either the plugin files or the instruction file, not both. If the plugin manifests are present, the host typically ignores the standalone [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) in favor of the plugin's integrated ruleset. According to the source code, the plugin tier is designed to supersede the fallback instruction file when installed.

### Which tier is better for CI/CD automation?

The **instruction-only tier** is generally preferable for CI/CD pipelines. Since it requires no host-specific plugin infrastructure and relies solely on [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md), it works consistently across containerized environments where plugin marketplaces may not be accessible. The static nature of the instruction-only tier ensures reproducible behavior without requiring state management or hook execution.

### How do I migrate from instruction-only to the plugin tier?

To migrate, remove or rename the standalone [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) file and install the appropriate host-specific plugin files (e.g., copy `.claude-plugin/` or `.codex-plugin/` directories into your repository). The plugin will then handle rule injection automatically through its lifecycle hooks. Ensure you commit the plugin manifest files and any hook scripts such as [`hooks/ponytail-activate.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-activate.js) to version control.

### Does the plugin tier work offline?

Yes, once installed, the plugin tier operates entirely from local files including [`plugin.json`](https://github.com/DietrichGebert/ponytail/blob/main/plugin.json), hook scripts, and skill definitions. However, features like auto-updates (documented in [`skills/ponytail-help/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-help/SKILL.md)) require network connectivity to query the host marketplace. The core functionality, including mode switching and skill execution, functions without an internet connection.