# How the ponytail-review Skill Works in the Ponytail Framework

> Understand how the ponytail-review skill works by injecting a markdown file into the LLM system prompt. This skill analyzes code for over-engineering patterns using standardized tags.

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

---

**The ponytail-review skill works by injecting the contents of [`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-review/SKILL.md) into the LLM's system prompt when review mode is active, constraining the model to analyze code exclusively for over-engineering patterns using standardized tags like `yagni` and `delete`.**

The ponytail-review skill is a Hermes plugin within the DietrichGebert/ponytail repository designed to identify unnecessary complexity in code changes. Unlike general code review tools, this skill operates by dynamically modifying the LLM's system context to enforce a strict "over-engineering-only" mindset, ensuring focused analysis without distraction from bug fixes or style issues.

## Mode Activation and Context Injection

The skill activates through two primary mechanisms: the `/ponytail review` slash command or the `PONYTAIL_DEFAULT_MODE` environment variable. When the runtime mode is set to `review`, the `build_injected_context()` function in [`__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/__init__.py) (lines 105-115) locates [`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-review/SKILL.md) and injects its entire contents as the LLM's system prompt. This injection effectively reconfigures the model to operate under an "over-engineering-only" constraint, stripping away general coding assistance capabilities in favor of targeted complexity analysis.

## Skill Registration Architecture

During the initialization phase, the `register(ctx)` function (lines 95-101) in [`__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/__init__.py) discovers available skills by scanning the `skills/` directory for subdirectories containing a [`SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/SKILL.md) file. The ponytail-review directory is automatically registered as a Hermes skill, making it available via the `/ponytail-review` command. This registration process binds the skill's markdown definition to the runtime environment, enabling dynamic loading without code changes to the core system.

## Slash Command Processing

User interaction with the skill flows through the `rewrite_gateway_command()` function (lines 59-64), which intercepts `/ponytail-review` invocations and rewrites them into standard agent prompts. The `_skill_prompt()` helper (lines 31-38) constructs the final prompt by combining the skill description from `SKILL_COMMANDS` with any user-provided arguments. This architecture allows seamless integration of skill-specific context into the conversation flow, ensuring the LLM receives precise instructions about what code to analyze and how to structure the response.

## Review Guidelines and Output Format

The operational logic governing the LLM's behavior resides entirely in [`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-review/SKILL.md) (lines 13-58). This specification defines:

- **Response format**: A concise, line-by-line audit of the provided diff
- **Classification tags**: `delete` (removable code), `stdlib` (standard library alternatives), `native` (built-in replacements), `yagni` (unnecessary abstractions), and `shrink` (simplifiable logic)
- **Strict boundaries**: Explicit prohibitions against bug fixes, style corrections, or any modifications—the skill must only report unnecessary complexity

The model adheres to these constraints because the entire SKILL.md content serves as its system prompt, effectively hardcoding the review philosophy into the conversation context.

## Usage Examples

To enable the skill and review code:

```python

# Activate review mode (sets PONYTAIL_DEFAULT_MODE internally)

await ctx.run_command("/ponytail review")

# Review a specific line or diff

await ctx.run_command("/ponytail-review repo.py:L88")

# Output: repo.py:L88: yagni: AbstractRepository with one implementation. Inline it.

# Return to standard mode

await ctx.run_command("/ponytail off")

```

When active, the LLM automatically applies the tagging system and formatting rules defined in SKILL.md without requiring manual prompt engineering.

## Summary

- **The ponytail-review skill** injects [`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-review/SKILL.md) into the LLM system prompt via `build_injected_context()` when review mode is active
- **Registration occurs** through `register(ctx)` scanning for SKILL.md files in the `skills/` directory
- **Command handling** uses `rewrite_gateway_command()` and `_skill_prompt()` to process `/ponytail-review` invocations with user arguments
- **Output constraints** include five specific tags (`delete`, `stdlib`, `native`, `yagni`, `shrink`) and strict prohibitions against applying fixes
- **Activation methods** include the `/ponytail review` command or `PONYTAIL_DEFAULT_MODE` environment variable

## Frequently Asked Questions

### How do I activate the ponytail-review skill?

You can activate the skill by running the `/ponytail review` slash command in your session or by setting the `PONYTAIL_DEFAULT_MODE` environment variable to `review`. Once activated, the `build_injected_context()` function automatically injects the skill's markdown specification into the LLM's system prompt, enabling the specialized review mode.

### What makes ponytail-review different from a standard code review?

Unlike general code review tools that check for bugs, style violations, or security issues, the ponytail-review skill constrains the LLM exclusively to identifying over-engineering. According to the DietrichGebert/ponytail source code, the SKILL.md file explicitly forbids the model from fixing bugs or applying changes—it must only report unnecessary complexity using the predefined tag system.

### What do the tags in the ponytail-review output mean?

The skill uses five standardized tags to categorize over-engineering: `delete` indicates code that should be removed entirely; `stdlib` suggests using standard library alternatives; `native` recommends built-in language features; `yagni` (You Aren't Gonna Need It) flags unnecessary abstractions; and `shrink` identifies logic that can be simplified or condensed. These tags appear at the beginning of each line in the audit output.

### Can the ponytail-review skill automatically fix the code it criticizes?

No, the skill is explicitly designed to report only. According to the specifications in [`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-review/SKILL.md) (lines 13-58), the model must never apply fixes, reformat code, or modify the original source. It produces a line-by-line audit of the diff, and the output is returned to the user unchanged for manual evaluation and implementation.