How to Use the ponytail-audit Skill for Whole-Repository Over-Engineering Audits

The ponytail-audit skill scans your entire codebase and produces a ranked list of over-engineered sections that can be deleted, simplified, or replaced with standard-library equivalents.

The ponytail-audit skill is one of six built-in capabilities in the Ponytail framework maintained at DietrichGebert/ponytail. This read-only analysis tool allows LLM agents to identify dead code, unnecessary wrappers, and hand-rolled alternatives to native features without modifying any source files.

Invoking the ponytail-audit Skill Across Different Hosts

The ponytail-audit skill operates on any host supporting the Ponytail skill protocol, though the invocation syntax varies by platform. All hosts ultimately route requests to the same underlying skill implementation defined in skills/ponytail-audit/SKILL.md.

Claude Code and Qoder

In Claude Code or Qoder environments, use the slash command:

/ponytail-audit

Codex

For Codex, prefix the command with an at-symbol:

@ponytail-audit

Pi Agent

The Pi agent registers the command in pi-extension/index.js using the sendAlias("/skill:ponytail-audit", "", ctx) function. Invoke it via:

pi /ponytail-audit

Or programmatically:

// Registration in pi-extension/index.js
pi.registerCommand("ponytail-audit", {
  description: "Run /skill:ponytail-audit",
  handler: (_args, ctx) => sendAlias("/skill:ponytail-audit", "", ctx),
});

// Execution in a session
await pi.runCommand("ponytail-audit");

Gemini CLI and Swival

For Gemini CLI, install the extension via gemini extensions install, then invoke /ponytail-audit. In Swival, first add the skill with swival skills add ponytail-audit, then trigger the audit using $ponytail-audit.

How the ponytail-audit Skill Works

The skill follows a deterministic pipeline defined in skills/ponytail-audit/SKILL.md, beginning with activation and ending with a plain-text report.

Activation and Execution

When you issue the appropriate command for your host, the slash-command handler calls sendAlias("/skill:ponytail-audit", "", ctx). This forwards the request to the skill engine without creating persistent state. The skill's meta-definition in SKILL.md instructs the agent to scan the entire repository, iterating over every file to apply hunt rules.

These rules specifically identify:

• Dead code and unreachable functions
• Hand-rolled standard library replacements
• Single-implementation factories
• Wrapper functions that only delegate to other functions

Tagging and Classification

Findings are labeled with one of five tags defined in the skill configuration:

• delete – Safe to remove entirely
• stdlib – Replace with standard library equivalent
• native – Replace with native platform feature
• yagni – "You Aren't Gonna Need It" – speculative code
• shrink – Candidate for length reduction

The tag determines the suggested replacement strategy for each finding.

Output Format and Impact Ranking

The agent ranks findings by estimated impact, listing the largest potential reductions first. Each finding appears on a single line:

<tag> <what to cut>. <replacement>. [path]

The report concludes with a net reduction summary:

net: -12 lines, -2 deps possible.

The skill is strictly read-only; it never writes files or changes code. To stop an active audit, type stop ponytail-audit or exit Ponytail mode using /ponytail off.

Key Implementation Files

Understanding the source files helps when customizing or debugging the ponytail-audit skill:

• skills/ponytail-audit/SKILL.md – Contains the complete skill definition, including YAML front-matter describing the purpose, tags, hunt criteria, output format, and operational boundaries.

• pi-extension/index.js – Registers the /ponytail-audit command and implements the handler that forwards to sendAlias("/skill:ponytail-audit", "", ctx).

• plugin.yaml – Declares ponytail-audit as an installable plugin component in the Ponytail ecosystem.

• skills/ponytail-help/SKILL.md – Provides the quick-reference table listing the audit command among other available Ponytail skills.

• commands/ponytail-help.toml – Stores human-readable help prompts displayed when users invoke the /ponytail-help skill.

Summary

• The ponytail-audit skill performs comprehensive, read-only scans to identify over-engineered code patterns across entire repositories.
• It supports multiple hosts including Claude Code (/ponytail-audit), Codex (@ponytail-audit), Pi Agent (pi /ponytail-audit), Qoder, Gemini CLI, and Swival ($ponytail-audit).
• Findings are classified using the tags delete, stdlib, native, yagni, or shrink and ranked by potential impact.
• Core implementation resides in skills/ponytail-audit/SKILL.md, with command registration handled in pi-extension/index.js.
• The skill outputs a plain-text, one-line-per-finding report showing exactly what to cut and potential line savings, suitable for copy-pasting into issue trackers.

Frequently Asked Questions

Does the ponytail-audit skill modify my code automatically?

No. According to the source code in skills/ponytail-audit/SKILL.md, the skill is strictly read-only. It generates a ranked report suggesting deletions and replacements, but you must implement changes manually. To halt an active scan, type stop ponytail-audit or disable Ponytail mode with /ponytail off.

What classification tags does the ponytail-audit skill use?

The skill applies five specific tags defined in its metadata: delete for removable code, stdlib for standard library replacements, native for native platform alternatives, yagni for speculative features, and shrink for verbose code that can be shortened. Each tag dictates the recommended replacement approach shown in the output.

How do I run ponytail-audit in Claude Code versus Codex?

In Claude Code, invoke the skill using /ponytail-audit. In Codex, use the at-prefixed command @ponytail-audit. Both route to the same underlying skill implementation in skills/ponytail-audit/SKILL.md, producing identical audit results regardless of host environment.

Where is the ponytail-audit skill defined in the repository?

The primary definition lives in skills/ponytail-audit/SKILL.md, containing the YAML front-matter that describes hunt rules and output formats. The Pi agent registers the command in pi-extension/index.js using the sendAlias function, while plugin.yaml declares it as an installable component in the Ponytail plugin system.

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