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 deficient across all dimensions. It provides no concrete actions, no natural trigger terms, no guidance on when to use it, and is so vague that it would be indistinguishable from numerous other skills. It reads more like a command reference than a functional description.
Suggestions
Define what 'refinement' means concretely — specify what inputs are refined, what actions are performed, and what outputs are produced (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 that describe scenarios a user would encounter (e.g., 'Use when the user asks to improve, polish, iterate on, or refine code, text, or other artifacts').
Remove the invocation syntax ('$agent-refinement') from the description — this is implementation detail, not selection criteria — and replace it with domain-specific keywords that help Claude distinguish this skill from others.
| 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 | Neither 'what does this do' nor 'when should Claude use it' is answered. The description only states it is an 'agent skill for refinement' and how to invoke it, providing no functional or contextual information. | 1 / 3 |
Trigger Term Quality | The only potentially relevant keyword is 'refinement,' which is vague and not a natural term users would use. The description focuses on invocation syntax ('$agent-refinement') rather than natural language triggers. | 1 / 3 |
Distinctiveness Conflict Risk | 'Refinement' is extremely generic and could apply to code refinement, text refinement, image refinement, prompt refinement, or any iterative improvement process. 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 reads like a general software engineering tutorial on TDD, refactoring, and error handling patterns rather than an actionable agent skill. It is extremely verbose, explaining concepts Claude already knows well (TDD cycles, circuit breakers, error hierarchies, cyclomatic complexity). It lacks a concrete workflow for how the refinement agent should operate on a given codebase and would benefit enormously from being condensed to essential, project-specific instructions with references to detailed examples.
Suggestions
Reduce content by 70-80%: Remove generic software engineering tutorials (TDD explanation, circuit breaker patterns, error hierarchy basics) and focus on the specific refinement workflow steps the agent should follow when invoked.
Add a clear, numbered workflow with validation checkpoints: e.g., 1) Identify areas to refine, 2) Run existing tests, 3) Apply improvements, 4) Validate tests pass, 5) Measure improvement metrics.
Split detailed code examples into separate reference files (e.g., EXAMPLES.md, PATTERNS.md) and keep SKILL.md as a concise overview with links.
Add concrete guidance on what triggers refinement, what inputs the agent expects, and what constitutes 'done' for a refinement cycle.
| 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 illustrative rather than project-specific, essentially teaching general software engineering patterns that Claude already understands. | 1 / 3 |
Actionability | The code examples are concrete and executable TypeScript, which is good. However, they are generic software engineering examples (authentication service, circuit breaker) rather than actionable instructions for a specific refinement workflow. There's no guidance on how to actually invoke this skill, what inputs it expects, or what outputs it produces in a real project 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. The skill lacks a clear step-by-step workflow for how the agent should approach refinement of actual code — when to stop, how to verify improvements, or how to decide what to refine first. | 2 / 3 |
Progressive Disclosure | All content is inlined in a single monolithic file with no references to external files. The massive code examples for error handling, circuit breakers, performance optimization, and complexity analysis should be split into separate reference files. The skill reads as a textbook chapter rather than a navigable skill document. | 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/ruflo
- Commit
398f7c2
- 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.