The 8,500-Star Skill That Makes Your Agent Wait for You
Eight thousand, five hundred and forty-six stars on SkillsMP. That's a lot of attention for a single skill, even in a marketplace that's been flooded with AI coding tools. Plannotator sits at the intersection of two things developers actually care about: keeping humans in the loop and giving agents a real feedback surface instead of a rubber-stamp approval flow. It's not trending upward right now—zero stars gained in the last week—but the cumulative count tells me this is a tool people install and keep using, not a flash in the pan.
I went through the full SKILL.md, the README, and the GitHub repo before deciding whether to install it. Here's what I found.
What This Skill Actually Does
Plannotator is not a prompt engineering trick or a wrapper around another LLM. It's a local CLI binary that spins up a browser-based annotation UI and blocks your agent's workflow until a human makes a decision. Think of it as a review gate: your agent proposes a plan, writes code, or generates an artifact, Plannotator opens it in the browser, you mark it up with comments and annotations, and the structured feedback comes back to stdout so the agent can act on it.
The skill itself is the knowledge layer—the command reference and session model that tells Claude Code (or Codex, or any supported agent) how to invoke the CLI correctly. There are thinner companion skills (plannotator-review, plannotator-annotate, plannotator-last) for the three most common actions, but this reference skill is where you go when you need to pick the right flags yourself.
Why It Matters
The gap this fills is real and underappreciated. Most agent workflows today are either fully autonomous (dangerous) or require you to manually paste feedback into a chat (fragile). Plannotator gives you a proper review surface—inline annotations, comments, approval/dismiss/annotate decisions—that feeds back into the agent's context programmatically. No copy-paste, no hallucinating what you said, no losing track of which comment was about what.
It also solves the "plan review" problem specifically. When your agent exits plan mode, the hook fires automatically and opens the plan in the annotation UI. You don't have to remember to run anything. The human decision comes back as structured data the agent can interpret. That's a meaningful quality-of-life improvement over the current norm of just reading a plan in a chat window and typing "looks good."
Key Capabilities
1. Automatic plan review via hooks. The skill explicitly says you should never run bare plannotator for plan review—the hook handles it on plan exit. This is well-architected: it removes friction and ensures every plan gets a human look before execution.
2. Multi-surface annotation. Files (markdown, text, config, HTML), URLs (via Jina Reader or Turndown), running local apps, folders, and even the last assistant message all go through the same annotation UI. The --gate and --json flags give you structured decision output that agents can parse without guessing.
3. Code review with VCS intelligence. plannotator review auto-detects Git, GitButler, Jujutsu, and Perforce. It handles PR URLs from GitHub and GitLab, supports --base for layered branch reviews, and the --tailscale flag lets you publish a review session over your tailnet if you're working remotely. The diff model is "everything a PR would show now" by default, which is the right mental model.
4. Honest session semantics. The skill is clear about what happens when a session ends without a decision: it reads as "no feedback." It also warns you not to kill the process to "finish" a review. That kind of documentation honesty is rare and appreciated.
5. --hook mode for real hook contexts. The --hook flag emits machine-readable JSON ({"decision":"block","reason":"..."}) that works in PostToolUse/Stop hook contexts. It's explicitly marked as annotate-only and never for interactive use. The skill author clearly thought about the integration surface carefully.
Who Should Install This (and Who Shouldn't)
Install it if: you use Claude Code, Codex, or any of the nine supported agents and you regularly review plans or code before letting the agent proceed. If you've ever been burned by an agent executing a plan you only half-read, this is the safety net. If you work in a team where code review culture matters, the PR/MR review mode is a genuine productivity win.
Don't install it if: you're the type of developer who trusts your agent completely and never wants to interrupt a workflow. Plannotator is designed to block—you'll be waiting in the browser while the CLI process hangs. If you're working in a terminal-only environment without a browser nearby, the whole model breaks. And if you're using an agent that's not on the supported list (check the README for the full roster), you're out of luck.
Concerns and Limitations
The biggest friction point is the blocking session model. Every review or annotate command starts a server, opens a browser, and waits. If you're running agents in automated pipelines or CI, this doesn't fit. The skill acknowledges this—you can run it in the background with a long timeout—but the UX still assumes a human sitting in front of a browser.
The 8,546-star count with zero growth in the last week is worth noting. It could mean the tool has saturated its early-adopter audience, or it could mean the marketplace algorithm is shifting. Either way, it's not a signal of current momentum, and I'd watch the next few weeks before committing to the workflow.
The --base and --diff-type flags are git-only and will error on JJ, GitButler, Perforce, and multi-repo workspace reviews. That's a limitation the skill documents honestly, but it's still a constraint that caught me off guard when I first read the reference. And the --env file refusal (.env itself is blocked) is a security feature, not a bug, but it means you can't annotate your own environment files even when you might want to.
Verdict
Plannotator is the most thoughtfully designed agent-review skill I've evaluated. The SKILL.md is genuinely well-written—clear command tables, honest session semantics, explicit warnings about what not to do. The multi-agent support and VCS intelligence show real engineering effort. The blocking model isn't for everyone, but for developers who want a real human review gate, it's exactly the right tradeoff.
Install it. Use plannotator review for code, let the hooks handle plan review automatically, and reach for plannotator annotate --gate --json when you need to approve a generated spec. Just don't expect it to fit into a fully automated pipeline.
SkillsMP: https://skillsmp.com/creators/backnotprop/plannotator/apps-skills-core-plannotator GitHub: https://github.com/backnotprop/plannotator/tree/main/apps/skills/core/plannotator