simplify-and-harden
Post-completion self-review for coding agents that runs simplify, harden, and micro-documentation passes on non-trivial code changes. Use when: a coding task is complete in a general agent session and you want a bounded quality and security sweep before signaling done. For CI pipeline execution, use simplify-and-harden-ci.
58
66%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugin/skills/simplify-and-harden/SKILL.mdQuality
Discovery
85%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a strong description that clearly defines its niche as a post-completion code review skill with three specific passes. It excels at completeness by providing both what/when guidance and even disambiguating from a related CI skill. The main weakness is that trigger terms lean toward specialized jargon rather than natural user language, which could reduce discoverability when users ask for common tasks like 'review my code' or 'clean up this code'.
Suggestions
Add more natural trigger terms users might say, such as 'review my code', 'clean up', 'refactor', 'code quality check', or 'security review' to improve discoverability.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists three specific concrete actions: 'simplify', 'harden', and 'micro-documentation passes on non-trivial code changes'. These are distinct, named operations that describe what the skill does. | 3 / 3 |
Completeness | Clearly answers both 'what' (simplify, harden, and micro-documentation passes on non-trivial code changes) and 'when' (when a coding task is complete and you want a bounded quality/security sweep before signaling done). Also includes a disambiguation clause for CI pipeline use cases. | 3 / 3 |
Trigger Term Quality | Includes some relevant terms like 'coding agents', 'quality and security sweep', 'self-review', and 'code changes', but misses common natural user phrases like 'review my code', 'clean up', 'refactor', or 'code review'. The terms are somewhat specialized/jargon-heavy ('micro-documentation passes', 'harden'). | 2 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with a clear niche: post-completion self-review for coding agents. The explicit disambiguation from 'simplify-and-harden-ci' for CI pipelines further reduces conflict risk. The specific combination of simplify + harden + micro-documentation is unique. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
47%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill demonstrates excellent workflow design with clear three-pass sequencing, explicit approval gates, and well-defined scope constraints. However, it is severely over-long for a skill file, explaining concepts Claude already knows (security checklist items, what dead code is) and inlining content that belongs in reference files (full output schema, configuration examples, agent compatibility lists). The actionability is moderate — checklists are clear but integration code is pseudocode for hypothetical APIs.
Suggestions
Cut the content by 50-60%: remove the Rationale/Philosophy section, trim the security/simplify checklists to just the item names (Claude knows what SQL injection and dead code are), and move the full output schema, configuration example, and agent compatibility list to referenced files.
Move the complete YAML output schema to a separate `references/output-schema.md` file and keep only a 3-4 line summary of key output fields inline.
Move the configuration example and integration notes (programmatic + prompt-based) to `references/integration-guide.md` — the main skill file should just state the three passes, scope rules, budget limits, and stop hook behavior.
Replace the pseudocode programmatic integration example with either a real executable snippet for one specific agent or remove it entirely in favor of the prompt-based integration which is more universally actionable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~400+ lines. It explains philosophy, rationale, and concepts Claude already understands (what dead code is, what injection vectors are, what race conditions are). The metadata table, agent compatibility list, and extensive configuration examples add significant token bloat. The 'Rationale and Philosophy' section is entirely unnecessary context-setting. | 1 / 3 |
Actionability | The skill provides concrete checklists, a detailed output schema, and example prompt-based integration text that is copy-paste ready. However, the programmatic integration code is pseudocode for a hypothetical API rather than executable code, and the actual review steps are checklist-based guidance rather than precise executable instructions. The refactor stop hook examples are illustrative mockups, not real implementations. | 2 / 3 |
Workflow Clarity | The three-pass workflow (Simplify → Harden → Document) is clearly sequenced with explicit validation checkpoints. The Refactor Stop Hook provides a clear feedback loop requiring human approval before proceeding. Budget limits serve as explicit stopping conditions, and the categorization of actions (cosmetic vs refactor, patch vs security refactor) provides clear decision gates throughout. | 3 / 3 |
Progressive Disclosure | The skill references external files appropriately (references/design-decisions.md, references/agent-context-snippets.md, simplify-and-harden-ci) and mentions a learning loop integration with self-improvement skill. However, the main file itself is monolithic — the full output schema (~80 lines of YAML), complete configuration example, integration notes, and agent compatibility list should be in referenced files rather than inline. The content that is inline far exceeds what belongs in an overview. | 2 / 3 |
Total | 8 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- pskoett/pskoett-ai-skills
- Commit
fe0da1c
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.