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

> Learn to use the ponytail-audit skill to scan your entire codebase. Discover and simplify over-engineered sections, saving time and effort.

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

---

**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`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-audit/SKILL.md).

### Claude Code and Qoder

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

```text
/ponytail-audit

```

### Codex

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

```text
@ponytail-audit

```

### Pi Agent

The Pi agent registers the command in [`pi-extension/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js) using the `sendAlias("/skill:ponytail-audit", "", ctx)` function. Invoke it via:

```text
pi /ponytail-audit

```

Or programmatically:

```javascript
// 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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js)** – Registers the `/ponytail-audit` command and implements the handler that forwards to `sendAlias("/skill:ponytail-audit", "", ctx)`.

- **[`plugin.yaml`](https://github.com/DietrichGebert/ponytail/blob/main/plugin.yaml)** – Declares `ponytail-audit` as an installable plugin component in the Ponytail ecosystem.

- **[`skills/ponytail-help/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-help/SKILL.md)** – Provides the quick-reference table listing the audit command among other available Ponytail skills.

- **[`commands/ponytail-help.toml`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-audit/SKILL.md), with command registration handled in [`pi-extension/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js) using the `sendAlias` function, while [`plugin.yaml`](https://github.com/DietrichGebert/ponytail/blob/main/plugin.yaml) declares it as an installable component in the Ponytail plugin system.