# What Is the Purpose of the ponytail-audit Skill? Complete Guide to Repository Over‑Engineering Detection

> Discover the purpose of the ponytail-audit skill. This comprehensive guide explains how it detects over-engineering in your repository by scanning files and identifying removable or replaceable items.

- Repository: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
- Tags: getting-started
- Published: 2026-09-06

---

**The ponytail‑audit skill performs a read‑only, whole‑repository audit for over‑engineering, scanning every file to produce a ranked list of items that can be removed, simplified, or replaced with standard‑library or native alternatives.**

Unlike line‑level code review tools, `ponytail‑audit` targets structural bloat across an entire codebase. This article explains how the skill works, how to invoke it, and how to interpret its output based on the source code in the DietrichGebert/ponytail repository.

---

## How ponytail‑audit Differs from ponytail‑review

The ponytail project provides two primary analysis skills with distinct scopes:

- **ponytail‑review** – Examines only the current diff (changed code)
- **ponytail‑audit** – Scans every file in the repository

This distinction matters for maintenance workflows. While `ponytail‑review` catches issues in new commits, `ponytail‑audit` surfaces accumulated technical debt that spans the entire codebase. According to the skill manifest at [`skills/ponytail-audit/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-audit/SKILL.md), the audit skill is explicitly designed for "hunting rules" that identify candidates for deletion or replacement.

---

## Triggering and Stopping the ponytail‑audit Skill

Users activate the skill through natural language or a slash command. The command configuration at [`commands/ponytail-audit.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-audit.toml) registers `/ponytail-audit` as the primary invocation.

### Invocation Patterns

```text

# Basic repository‑wide audit

/ponytail-audit

# Targeted audit of a specific directory

/ponytail-audit src/

```

### Alternative Triggers

Natural language equivalents also work:

- "audit this codebase"
- "find bloat"

### Halting an Audit

To stop a running audit and return to normal interaction:

```text
stop ponytail-audit

```

or

```text
normal mode

```

---

## Understanding ponytail‑audit Output Format

The skill produces a machine‑readable, one‑line‑per‑finding report. Each line follows a strict structure documented in [`skills/ponytail-audit/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-audit/SKILL.md):

```

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

```

### Tag Categories

| Tag | Meaning |
|-----|---------|
| `delete` | Entirely unused code that can be removed |
| `stdlib` | Custom implementation replaceable with standard library |

### Example Output

```text
delete unusedHelper. . [src/helpers/unusedHelper.ts]
stdlib customDateParser. parseISO (from date-fns). [src/utils/date.ts]
net: -12 lines, -1 deps possible.

```

The final summary line quantifies potential savings: `net: -<N> lines, -<M> deps possible.`

---

## Key Implementation Files

The ponytail‑audit skill is implemented across several files that define its behavior, registration, and portability:

- **[`skills/ponytail-audit/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-audit/SKILL.md)** – Skill definition including tags, hunting rules, and output format specification
- **[`commands/ponytail-audit.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-audit.toml)** – Command configuration binding the skill to `/ponytail‑audit`
- **[`plugin.yaml`](https://github.com/DietrichGebert/ponytail/blob/main/plugin.yaml)** – Lists `ponytail‑audit` as a provided skill for plugin hosts
- **[`docs/agent-portability.md`](https://github.com/DietrichGebert/ponytail/blob/main/docs/agent-portability.md)** – Documents export to agents including Qoder, Pi, and OpenClaw
- **[`tests/qoder-plugin.test.js`](https://github.com/DietrichGebert/ponytail/blob/main/tests/qoder-plugin.test.js)** – Validates correct registration and invocation of the audit command

The [`plugin.yaml`](https://github.com/DietrichGebert/ponytail/blob/main/plugin.yaml) file is particularly important for distribution: it registers the skill for consumption by external agent platforms. The portability documentation at [`docs/agent-portability.md`](https://github.com/DietrichGebert/ponytail/blob/main/docs/agent-portability.md) explains how the same skill definition operates across different AI coding assistants.

---

## Read‑Only Design Philosophy

The ponytail‑audit skill is intentionally **read‑only**. It reports findings but never applies changes. This separation of concerns allows developers to:

1. Review proposed deletions and replacements
2. Validate that suggested standard‑library alternatives meet requirements
3. Apply changes through their preferred workflow (manual edit, automated refactor, or separate tool)

This design reflects a conservative approach to codebase modification present throughout the ponytail project architecture.

---

## Summary

- **ponytail‑audit** scans entire repositories for over‑engineering, unlike diff‑based `ponytail‑review`
- Output uses a compact `<tag> <what to cut>. <replacement>. [path]` format with a net savings summary
- Invocation via `/ponytail‑audit`, natural language, or directory‑scoped `/ponytail‑audit src/`
- Defined in [`SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/SKILL.md), registered in `commands/ponytail‑audit.toml`, and exported through [`plugin.yaml`](https://github.com/DietrichGebert/ponytail/blob/main/plugin.yaml)
- Read‑only by design: reports findings without applying changes

---

## Frequently Asked Questions

### What is the difference between ponytail‑audit and ponytail‑review?

**ponytail‑review** examines only the current diff—code changed in a commit or PR. **ponytail‑audit** performs a whole‑repository scan for accumulated bloat. According to the [`SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/SKILL.md) manifest, audit hunting rules target structural over‑engineering rather than line‑level issues.

### Can ponytail‑audit automatically fix the issues it finds?

No. The skill is explicitly read‑only. It produces a ranked report for human or scripted review but never modifies files. This is documented in the skill definition and preserved across all agent platforms via [`plugin.yaml`](https://github.com/DietrichGebert/ponytail/blob/main/plugin.yaml).

### How do I run ponytail‑audit on just part of my codebase?

Pass a directory path as an argument: `/ponytail‑audit src/`. The skill supports targeted audits while maintaining the same output format and tagging system defined in its hunting rules.

### Where is the ponytail‑audit skill configuration stored?

The primary definition lives at `skills/ponytail‑audit/SKILL.md`. Command registration is in `commands/ponytail‑audit.toml`, and plugin host integration is declared in [`plugin.yaml`](https://github.com/DietrichGebert/ponytail/blob/main/plugin.yaml) at the repository root.