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 available options.
Suggestions
Define what 'refinement' means in this context — specify the concrete actions performed (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 distinguish this skill from others — specify what type of content is refined (code, prose, designs, etc.) and what the refinement process entails.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description contains no concrete actions whatsoever. 'Refinement' is abstract and undefined — 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 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 an invocation command ('$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 refinement, text refinement, design refinement, etc. This would 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 reads as a generic TypeScript development tutorial covering TDD, error handling, performance optimization, and code quality — all topics Claude already understands well. It is extremely verbose with no project-specific guidance, no clear invocation workflow, and no progressive disclosure. The content would benefit from being reduced to a concise checklist of refinement steps with project-specific tooling references.
Suggestions
Reduce the body to a concise refinement checklist (under 50 lines) with specific steps Claude should take when invoked, rather than teaching general TDD and design patterns.
Remove generic code examples (authentication service, circuit breaker) and replace with project-specific patterns or references to actual codebase conventions.
Add explicit validation checkpoints: e.g., 'Run tests after each change', 'Verify coverage thresholds before completing', with specific commands.
Split detailed reference material (error handling patterns, performance optimization techniques) into separate bundle files and link from a concise overview.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~350+ lines. Explains TDD concepts (Red/Green/Refactor), circuit breakers, error hierarchies, and complexity analysis — all things Claude already knows. The entire skill reads like a tutorial/textbook rather than a concise reference. Most code examples are illustrative rather than project-specific, adding no unique value. | 1 / 3 |
Actionability | Code examples are concrete and executable TypeScript, which is good. However, they are generic examples (authentication service, circuit breaker) not tied to any specific project or tooling. There are no specific commands to run, no project-specific paths, and no clear instructions for what Claude should actually do when invoked — it's more of a teaching document than an actionable skill. | 2 / 3 |
Workflow Clarity | The TDD Red/Green/Refactor phases provide a sequence, but there are no explicit validation checkpoints, no feedback loops for error recovery, and no clear decision points. The 'Best Practices' section is a generic bullet list. For a refinement workflow involving code changes, there should be explicit verify-before-proceeding steps. | 2 / 3 |
Progressive Disclosure | Monolithic wall of content with no references to external files. All content — TDD examples, performance optimization, error handling, circuit breakers, quality metrics, complexity analysis — is inlined in a single massive file. Much of this could be split into separate reference documents with a concise overview in the main skill. | 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
9d4a9ea
- 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.