moonlight-lupin/agent-skills / software-development/skill-quality-review
skill-quality-review
VerifiedUse when auditing or reviewing skill quality — batch checks across a library, deep per-skill grep methodology, usage stats, efficacy testing, or fix planning. Single consolidated home for the writing-for-agents review framework and the 3-surface review methodology.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 33.1 KB |
| references/batch-checks.md | markdown | 23.4 KB |
| references/claude-plugin-review.md | markdown | 10.8 KB |
| references/domain-passive-voice.md | markdown | 1.8 KB |
| references/efficacy-ab-test.md | markdown | 6.3 KB |
| references/fix-phase-pitfalls.md | markdown | 3.3 KB |
| references/hermes-library-review.md | markdown | 3.3 KB |
| references/independent-skills.md | markdown | 2.1 KB |
| references/recurring-failure-patterns.md | markdown | 15.0 KB |
| references/skill-review-methodology.md | markdown | 38.9 KB |
| references/writing-for-agents-framework.md | markdown | 12.2 KB |
| scripts/add_toc.py | script | 5.8 KB |
| scripts/check_calls.py | script | 26.2 KB |
| scripts/check_references.py | script | 6.3 KB |
| templates/efficacy-rubric-template.md | markdown | 1.1 KB |
| tests/acceptance.md | markdown | 1.5 KB |
| tests/test_harness_acceptance.py | script | 4.7 KB |
references/fix-phase-pitfalls.md
View on GitHub# Fix-phase pitfalls — orchestrating multi-agent skill fixes
Discipline for the fix phase after a skill review: batching, parallel agents, and proof-of-no-loss. Lessons from the pere-toolkit best-practices batches (5-6 Oct 2026, five agents in parallel across 52 skills).
## 1. Order the batches so trimming comes last
Fixing callability ADDS lines (pere: about +480); the conciseness pass then removed 522. Trimming first would have cut text the call lines needed, and the trimmers could have deleted the new call lines. Run conciseness on settled text — always last.
## 2. Prove nothing load-bearing was lost
After a conciseness pass, run a scripted check that every code span and CLI command in the previous commit is still present in the new text (verbatim span match over `git diff HEAD~1 --name-only`). Pere's check flagged 7 spans; all were generic signatures beside surviving concrete calls — the flagged-but-surviving rule from Check 15 interpretation. Report the count and disposition in the batch summary.
## 3. Regex boilerplate replacement eats neighbours
A pattern like `…end of paragraph\.[^\n]*$` deleted text that carried on after the paragraph on the same line, in 4 of 47 files. One was the opening of a call line. Rules:
- Match to the paragraph end only, never to end-of-line blindly.
- Diff every replaced span against HEAD before committing.
## 4. CRLF from Python writers
Agents' Python edits wrote CRLF line endings twice (platform-dependent default). Put `open(p, "w", encoding="utf-8", newline="\n")` in every agent prompt that writes files, and lint for CRLF (`grep -rlP '\r$'` over changed files) before commit.
## 5. Shared resources make parallel test runs flaky
Agents each running the full test suite fought over LibreOffice; recalc tests failed at random, though each passed on a solo run. Tell agents to REPORT such failures, not chase them, and have the orchestrator run the suite solo before each commit.
## 6. Announce a new lint rule before agents run tests
Adding a lint rule (pere: the TOC rule) mid-batch made every agent's "suite must be green" gate fail. Message agents first, or land the rule after their batch completes.
## 7. Partition by file; keep the orchestrator out of agents' files mid-run
Mechanical cross-cutting edits (boilerplate, TOCs) go before or after an agent batch, never during. This extends the SKILL.md pitfall on parallel write conflicts — the safe pattern is partition by directory or file, with the orchestrator touching only files no agent owns.
## 8. Verify reviewer findings before fixing
Two independent reviewers plus a re-check still produced three false findings on pere (IM terminology, return-on-cost, "pywin32 missing"). Each finding needs a quoted locator and a spot-check before it becomes a fix task. Counts come from scripts, not reviewer estimates.
## Batch sequencing template
1. Mechanical pre-pass (frontmatter, TOCs, packages) — orchestrator, scripted.
2. Agent batch, partitioned by file (callability + instructions + defaults fixes together per skill). Prompt includes: newline="\n" in every open(), report-don't-chase for flaky tests, new lint rules announced.
3. Orchestrator solo test run + commit.
4. Terminology / boilerplate / conciseness pass on the now-settled text.
5. No-loss proof (§2) + final full check re-run.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |