agent-refinement
Agent skill for refinement - invoke with $agent-refinement
43
13%
Does it follow best practices?
Impact
96%
1.23xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.agents/skills/agent-refinement/SKILL.mdQuality
Discovery
0%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 description is critically underspecified. It provides no concrete actions, no domain context, no trigger terms, and no guidance on when to use the skill. It reads more like a label than a functional description, making it nearly impossible for Claude to correctly select this skill from a pool of options.
Suggestions
Specify what is being refined (e.g., code, text, designs, prompts) and list concrete actions the skill performs (e.g., 'Iteratively improves code quality by analyzing structure, reducing complexity, and applying best practices').
Add an explicit 'Use when...' clause with natural trigger terms users would say (e.g., 'Use when the user asks to improve, polish, iterate on, or refine code/text/output').
Narrow the domain to a clear niche to reduce conflict risk with other skills (e.g., 'Refines Python code for readability and performance' rather than generic 'refinement').
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description contains no concrete actions whatsoever. 'Refinement' is abstract and vague — it does not specify what is being refined, how, or what outputs are produced. | 1 / 3 |
Completeness | The description fails to answer both 'what does this do' and 'when should Claude use it.' There is no explanation of capabilities and no 'Use when...' clause or equivalent trigger guidance. | 1 / 3 |
Trigger Term Quality | The only potentially relevant keyword is 'refinement,' which is not a natural term users would typically say. The description includes a command invocation ('$agent-refinement') but no natural language trigger terms. | 1 / 3 |
Distinctiveness Conflict Risk | 'Refinement' is extremely generic and could apply to virtually any iterative improvement task — code refactoring, text editing, design iteration, etc. This would easily conflict with many other skills. | 1 / 3 |
Total | 4 / 12 Passed |
Implementation
27%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is a verbose collection of generic TypeScript patterns (TDD, error handling, circuit breakers, performance optimization) that Claude already knows. It reads more like a tutorial or textbook chapter than a concise skill instruction. The content lacks project-specific context, clear decision frameworks for when to apply each technique, and any progressive disclosure structure.
Suggestions
Reduce content to under 100 lines by removing generic patterns Claude already knows (TDD, circuit breakers, error hierarchies) and focus on project-specific refinement workflows and decision criteria.
Add explicit validation checkpoints: e.g., 'Run test suite before and after each refactoring step; abort if coverage drops below threshold.'
Split detailed code examples into separate reference files (e.g., PATTERNS.md, ERROR_HANDLING.md) and keep SKILL.md as a concise overview with links.
Add concrete decision criteria for when to apply each refinement technique rather than just listing patterns (e.g., 'If response time > 200ms, check hot paths; if cyclomatic complexity > 5, extract strategy pattern').
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~400+ lines. Explains basic concepts Claude already knows (TDD red/green/refactor, what circuit breakers are, what error hierarchies are, cyclomatic complexity). The lengthy code examples are generic patterns not specific to any project context, making most tokens unnecessary. | 1 / 3 |
Actionability | Code examples are concrete and executable TypeScript, which is good. However, they are generic cookbook patterns (authentication service, circuit breaker, retry decorator) rather than specific guidance for a particular codebase or task. There's no clear instruction on when/how to apply these patterns in context. | 2 / 3 |
Workflow Clarity | The TDD Red-Green-Refactor phases are sequenced, but there are no explicit validation checkpoints or feedback loops for the overall refinement process. No clear decision criteria for when refinement is 'done' or how to prioritize which refinements to apply. The numbered steps within each section are present but lack verification gates. | 2 / 3 |
Progressive Disclosure | Monolithic wall of text with all content inline. No references to external files for detailed patterns. The entire authentication service example, circuit breaker implementation, error hierarchy, and performance optimization are all dumped into a single file when they could be split into focused reference documents. | 1 / 3 |
Total | 6 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (530 lines); consider splitting into references/ and linking | Warning |
Total | 10 / 11 Passed | |
- Repository
- ruvnet/claude-flow
- Commit
f547cec
- 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.