Agent skills are having a moment — but finding one that actually works is still trial-and-error. Most "skill directories" are scraped lists of repo names and README blurbs. Nobody tells you what happens when you actually run the thing.
So I ran them myself. I took 7 skills that all promise to fix your code comments and documentation, fed each one the same uncommented Python files, and compared the outputs line by line. No vibes — same input, same rubric, real outputs.
Spoiler: only 3 are worth your time, and which one depends entirely on the job you're hiring it for.
The test setup
Two test files, deliberately realistic:
- A 32-line order/discount module — two functions, business rules buried in conditionals, and a silent edge case (out-of-stock items are skipped without any error or warning)
- A 212-line module with 3 classes, 2 enums, 2 dataclasses, and 5 standalone functions — the kind of file you actually need documented
Each skill was scored on four axes: does it do the job, does it run reliably, is the output good, and how much hand-holding does it need.
Winner #1: doc-sync (8/10) — the bulk documentation machine
The highest scorer, and it wasn't close. It documented everything: module-level docstring with a component overview, every enum member explained, every dataclass field, every method, every standalone function — all in proper Google Style. Algorithm functions even got formula explanations and Example sections.
On the 212-line file it produced roughly 760 lines of documentation. It also ships an optional KB sync (ChromaDB), and when ChromaDB wasn't installed in my environment it fell back to JSONL without complaining. Small detail, but it's the kind of thing that separates tested software from README software.
The catch: thorough to a fault. Trivial functions get the full Args/Returns ceremony. Python and Go only.
Hire it for: documenting an entire existing codebase in one sweep.
Winner #2: code-comment (7/10) — the minimalist (my personal favorite)
The opposite philosophy, executed ruthlessly: comment only the why, never the what. On the 32-line file it added exactly 3 comments — the fewest of all seven — and every one earned its place. It caught the business context behind the discount tiers, the silent out-of-stock skip, and the fallback logic for when a discounted price would exceed the original. Meanwhile it deliberately left the accumulation loop, the field assignments, and the return dict uncommented — because a senior dev wouldn't explain those either.
No "increment i by 1" noise. No AI-flavored filler. The output reads like annotations from someone who's been on-call for this code.
The catch: it cleans and refines more than it generates. Point it at completely uncommented code and you'll write the first pass yourself. It's an editor, not an author.
Hire it for: making existing comments better, or if you believe most comments are noise.
Winner #3: python-docstring-linter (7/10) — the engineer's choice
The most technically serious of the batch. It doesn't just generate docstrings — it runs pydocstyle before and after, parses your code with ast, and closes a verify-generate-reverify loop. In my test: 5 violations down to 0, with Google, NumPy, and Sphinx formats all passing. Type inference is a three-level fallback (annotations, then defaults, then parameter-name heuristics), which is smarter than most.
The catch: English-only output, and the inference degrades on domain-specific names — one function returning parsed JSON got labeled Any because its word bank didn't know the domain. Summary sentences come from a vocabulary mapping, so unfamiliar domains get template-y phrasing.
Hire it for: CI-style docstring compliance, where "provably passes pydocstyle" matters more than prose quality.
The ones I'd skip
code-commenter (6/10). The cleanest, most standard output of all seven — proper Google-style docstrings, accurate inline notes. But there is zero automation: the skill is essentially a style guide, and you do all the work. If I wanted to write comments by hand against a checklist, I'd just... do that.
code-comment-standard (6/10). The most thorough (types, value ranges, constraints, exceptions) and it even flagged a latent bug in my test file — a counter that included skipped items. Impressive. But it's Java/Javadoc-oriented, so Python users are constantly translating conventions in their head, and it adds formality Python culture doesn't want (author, since at module level).
code-comment-generator01 (5/10). The only one with real automation scripts (analyze, then insert), which I was rooting for. But the insert step mangled indentation in a whitespace-sensitive language, and the comment style is the classic AI tell — semicolon-separated "parameter: x; returns: y" lists pasted above the function instead of docstrings inside it. I spent the time it saved me on cleanup.
improve-code-comments (5/10). The best audit framework of the batch — Critical/High/Medium/Low severity tiers, a report-before-changes safety gate, a sensible delete-then-update-then-add order. Two problems: on uncommented code, two of its three phases have nothing to do, and — the ironic part — while auditing for filler comments it wrote filler comments itself ("subtotal = price x quantity", which its own rules say to delete).
What 7 tests actually taught me
The scores matter less than this: these skills differ more in purpose than in quality. There are three distinct jobs here, and each winner owns exactly one:
| Job | Skill | Score |
|---|---|---|
| Document a whole codebase | doc-sync | 8/10 |
| Minimalist "why-only" comments | code-comment | 7/10 |
| CI-enforceable docstring compliance | python-docstring-linter | 7/10 |
Pick the job first. A 5/10 skill for the right job beats an 8/10 skill for the wrong one — the generator with the indentation bug would still beat the minimalist if I needed 500 files annotated overnight and could tolerate cleanup.
One more thing I didn't expect: the README is a weak signal. The two most impressive READMEs in this batch belonged to 5/10 skills, and my favorite tool has the plainest docs of all. The only reliable test is running the thing on your code.
Full disclosure on method: I found most of these candidates through deep-skill-finder, a search tool where you describe the task in plain language and get skills back with test results attached, instead of keyword-matching repo names. I re-ran every test in this article myself before writing a word of it — that part is non-negotiable.
If there's a skill category you want tested next, name it in the comments. I've got a backlog, but reader requests jump the queue.
Top comments (0)