ponytail-debt Skill for Claude: A Ledger of Deferred Shortcuts

Makes Claude scan your repo for `shortcut:` comments and list each deferral as a row in a debt ledger.

Installs: 47.7K; on skills.sh
Stars: 182K; on GitHub
Updated: Oct 2026; last repo commit

You type /ponytail-debt, and the agent greps the repo for comments that start with shortcut: (or the older ponytail:). Each hit becomes one row: file and line, what was simplified, the limit it names, and when to revisit it. Rows with no revisit trigger get a no-trigger tag, and the report ends with a count.

Those comments are what the ponytail skill leaves behind when it takes a deliberate shortcut. You can pass your own marker word instead, like /ponytail-debt TODO. SKILL.md says it reads and reports only, and writes a file such as PONYTAIL-DEBT.md only if you ask.

Good for

Developers using ponytail who want to see what they deferred
Tech leads who want shortcuts tracked before they become permanent
Anyone who wants a quick list of TODO-style markers by file

Install ponytail-debt

Claude Code

Copy this prompt.

Install the ponytail-debt skill in Claude Code. Run this command:

npx skills add https://github.com/dietrichgebert/ponytail --skill ponytail-debt

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

Pick one route, not both. The skills CLI and folder routes install only ponytail-debt, a folder holding SKILL.md. The plugin route is the README install: it adds ponytail itself and all six skills, and also registers hooks and a task board (see Permissions and safety). Run the two plugin commands as separate prompts. Claude Code names plugin skills plugin-name:skill-name, so after the plugin install the full name may be /ponytail:ponytail-debt; the README lists /ponytail-debt.

From its listing on skills.sh. Source.

What's in the skill

When it loads

List every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.

Sections in SKILL.md

Scan
Output
Boundaries

Key facts

Author: dietrichgebert
Repository: dietrichgebert/ponytail
License: MIT
Installs on skills.sh: 47,723 (Nov 2, 2026)
GitHub stars: 182,027 (Nov 2, 2026)
Last repo commit: Oct 29, 2026
What installs: 1 file including SKILL.md (the folder holds SKILL.md only)
Hosts the README lists: Claude Code, Codex, Devin CLI, OpenCode, Gemini, Antigravity CLI, pi, Hermes Agent, Qoder, Grok Build (for ponytail commands)
Runs: A git grep over the repo; optional git blame for owners
Changes: Reads and reports only; writes a ledger file only if you ask

What it includes

Lists every shortcut: comment in the repo as a debt ledger
Triggers on /ponytail-debt, "ponytail debt", "what did ponytail defer", "list the shortcuts".
Try: “/ponytail-debt”
Runs code · /ponytail-debt
Searches comment lines for shortcut: or ponytail:, skipping .git and ignored files
The command is git grep --no-index --exclude-standard -nE with a comment-prefix pattern. Hits that are not a deferral, like a keyboard shortcut note, are skipped.
Runs code · Scan with git grep
Greps for your own word instead, such as /ponytail-debt TODO
Try: “/ponytail-debt TODO”
Runs code · Custom marker word
One row per marker: file:line, what was simplified, ceiling, upgrade trigger
Grouped by file. The ceiling and trigger come straight from the comment.
Ledger rows
Flags markers that name no upgrade path, because those silently rot
The report ends with "N markers, M with no trigger." or "No shortcut debt. Clean ledger."
no-trigger tag
Adds git blame for the marker line if you want an owner
Runs code · Owner per row (optional)
Writes the ledger to a file such as PONYTAIL-DEBT.md when you ask
Only on request.
Write · Save the ledger

From the official docs

Permissions

Low risk

It runs git commands in your repo and reads the comment text it finds. SKILL.md says it only reports, and writes a ledger file only if you ask.

What it can do

Read your data
Create and change things
Delete things
Read-only modeHow to turn it on

Watch out for

Plugin route registers hooks that run Node scripts
The plugin manifest points to hooks that run Node scripts at session start, when a subagent starts and on every prompt. The session-start script writes a flag file under your Claude config folder (default ~/.claude), runs a codebase-map script, and can copy a statusline script into that folder. Installing only this skill adds none of these.
It runs git commands in your repo
It runs git grep, and git blame if you ask for owners. The output, including comment text, goes to the model.
It writes a file only if you ask
Saving the ledger, for example to PONYTAIL-DEBT.md, is opt-in. Check the path before you agree.
Plugin route writes a task board to disk every turn
By default the band records one row per turn (cost, turns, agent time, tokens, reuse, tests) to ~/.config/ponytail/band/<project>.csv and rebuilds a board.html there. It runs git grep and grep over your repo and session transcript to compute them. /ponytail band import reads your past Claude Code sessions into the board.
Plugin route has an optional webhook
If you set a webhook URL in the plugin options, each task row is posted to it as JSON after every turn, with the task name unless you turn that off. The URL is empty by default and the token is stored in the system keychain, per the manifest.

Technical details

Turning on read-only	By default it reads and reports only; it writes a ledger file only when you ask.
Talks to	Only if you set the plugin webhook URL: your own endpoint

Questions

What does ponytail-debt do?

It collects every shortcut: comment (and older ponytail: comments) in your repo into one ledger, with the limit and the upgrade trigger for each. Rows with no trigger are tagged no-trigger.

What is a shortcut: comment?

Per the ponytail README, the ponytail skill writes them to mark a deliberate shortcut and when to revisit it. If you want another word, say so in your project's CLAUDE.md or AGENTS.md, then run /ponytail-debt with that word.

How do I install ponytail-debt?

Use the install box above. Its Claude Code tab has two routes: the skills CLI, which installs only ponytail-debt (a folder holding SKILL.md), and the full ponytail plugin from the README (two /plugin commands). Pick one, not both. There are also Claude app, Codex and skills CLI tabs.

Should I install the whole ponytail plugin instead?

The README's Claude Code route is the full plugin: two /plugin commands that add ponytail itself and its six skills. Beyond the skills, the plugin manifest registers hooks that run Node scripts at session start, when a subagent starts and on every prompt, plus a band above the prompt. By default its task board writes one row per turn to ~/.config/ponytail/band/<project>.csv, and an optional webhook URL is empty by default. Install the plugin if you want ponytail itself; install only this skill if you want just this command.

Does ponytail-debt need ponytail installed?

SKILL.md does not require it. It only searches for the marker word, so it also works with your own marker such as TODO. Without ponytail you may have no shortcut: comments and get "No shortcut debt. Clean ledger."

Is ponytail-debt safe?

It runs a git grep over your repo, and git blame if you ask for owners, then lists what it finds. SKILL.md says it reads and reports only and writes a file such as PONYTAIL-DEBT.md only on request. The comment text it finds goes to your AI model. The skill bundles no scripts and names no API key.

Information

updated Nov 2, 2026

Repository: dietrichgebert/ponytail
Folder: skills/ponytail-debt

dietrichgebert/ponytail skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 10

ponytail README · github.com
ponytail Claude plugin manifest · github.com
ponytail-debt SKILL.md · github.com
skills CLI commands · github.com
ponytail Codex plugin manifest · github.com
ponytail-help SKILL.md · github.com
ponytail-debt on skills.sh · skills.sh
ponytail hooks config · github.com
ponytail band module · github.com
ponytail session-start hook · github.com