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 for agent sessions. It effectively communicates what it does (simplify, harden, micro-documentation passes) and when to use it, and even disambiguates from a related CI-focused skill. The main weakness is that trigger terms lean toward specialized jargon rather than natural user language.
Suggestions
Add more natural trigger terms users might say, such as 'review my code', 'clean up code', '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' (runs simplify, harden, and micro-documentation passes on non-trivial code changes) and 'when' (when a coding task is complete and you want a 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', 'bounded quality sweep'). | 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 trigger context ('coding task is complete in a general agent session') makes it unlikely to conflict with other skills. | 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.
This skill has excellent workflow clarity with well-defined passes, validation checkpoints, and feedback loops for refactors. However, it is severely over-verbose — explaining philosophy, rationale, and concepts at length that don't add actionable value for an AI agent. The document would benefit enormously from aggressive trimming and moving detailed schemas, configuration examples, and integration patterns into referenced bundle files.
Suggestions
Cut the 'Rationale and Philosophy' section to 1-2 sentences max — Claude doesn't need motivation for why self-review is valuable. Similarly trim 'Agent Compatibility' which lists agents Claude already knows about.
Move the full output schema YAML example, configuration YAML, and integration code examples into separate referenced files (e.g., references/output-schema.md, references/configuration.md) to reduce the main file to an actionable overview.
Remove explanatory phrases throughout checklists like 'Agents tend to over-engineer' and 'This is the bread and butter of the skill' — these are commentary, not instructions.
Make the programmatic integration example either truly executable with a specific agent's API or remove it entirely in favor of the prompt-based integration which is more universally actionable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~400+ lines. Extensively explains philosophy, rationale, and concepts Claude already understands (what a self-review is, why peak context matters, what dead code is). The metadata table, agent compatibility list, and lengthy design philosophy sections consume significant tokens without adding actionable value. The output schema example alone is ~80 lines. Much of this could be cut by 60-70% without losing actionable content. | 1 / 3 |
Actionability | The checklists for Simplify and Harden passes are concrete and useful, and the prompt-based integration snippet is copy-paste ready. However, the programmatic integration code is pseudocode for a hypothetical API, the configuration YAML is illustrative rather than executable, and many instructions describe what the agent 'should' do rather than providing exact commands or executable steps. | 2 / 3 |
Workflow Clarity | The three-pass workflow (Simplify → Harden → Document) is clearly sequenced with explicit validation checkpoints. The Refactor Stop Hook provides a concrete feedback loop with approve/reject/skip options. Budget limits serve as explicit stopping conditions. The categorization of actions (cosmetic vs refactor, patch vs security refactor) with different approval requirements is well-defined. | 3 / 3 |
Progressive Disclosure | References to external files exist (references/design-decisions.md, references/agent-context-snippets.md, simplify-and-harden-ci) but no bundle files are provided, so we can't verify they exist. The SKILL.md itself is monolithic — the massive output schema, full configuration example, integration examples, and agent compatibility list could all be split into referenced files. The content that is inline far exceeds what belongs in an overview document. | 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
c9faa6f
- 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.