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 trigger terms, no 'when to use' guidance, and the word 'refinement' is too vague to distinguish this skill from any other editing or improvement-related skill. It is essentially unusable for skill selection among multiple options.
Suggestions
Define what 'refinement' means concretely — list specific actions such as 'iterates on drafts,' 'improves code quality,' or 'polishes prose' so Claude knows what this skill actually does.
Add an explicit 'Use when...' clause with natural trigger terms that describe the scenarios in which this skill should be selected (e.g., 'Use when the user asks to improve, polish, iterate on, or refine existing content').
Clarify the domain or scope to reduce conflict risk — specify whether this refines code, text, designs, or something else, so it can be distinguished from other editing or improvement skills.
| 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 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 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 editing, improving, or iterating task. This would conflict with many other skills that involve any form of content improvement. | 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 more like a generic software engineering tutorial on TDD, error handling, and performance optimization than an actionable agent skill. It is extremely verbose, explaining well-known patterns Claude already understands, while lacking specific operational guidance on what to do when invoked. The content would benefit from drastic reduction to focus on the specific refinement workflow steps and decision criteria rather than teaching general programming concepts.
Suggestions
Reduce content to under 80 lines by removing generic code examples (TDD, circuit breakers, error hierarchies) that Claude already knows, and focus on the specific decision-making process and steps for refinement.
Add a clear, numbered operational workflow: what Claude should do first when invoked (e.g., analyze existing code, run tests, identify issues), with explicit validation checkpoints between steps.
Split detailed reference examples (error handling patterns, performance optimization techniques) into separate bundle files and reference them from a concise overview.
Replace the generic authentication service example with guidance on how to assess and refine arbitrary codebases — e.g., what metrics to check, what refactoring patterns to apply, and when to stop iterating.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~350+ 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 software engineering patterns, not specific operational guidance. Most content could be removed without losing actionable value. | 1 / 3 |
Actionability | The code examples are concrete and executable TypeScript, which is good. However, they are generic software engineering patterns (authentication service, circuit breaker, error handling) rather than specific instructions for what Claude should do during a 'refinement phase.' There's no guidance on how to analyze a given codebase, what tools to run, or what specific steps to take when invoked. | 2 / 3 |
Workflow Clarity | The TDD Red-Green-Refactor phases provide a loose sequence, but there are no explicit validation checkpoints, no feedback loops for error recovery, and no clear workflow for what Claude should actually do when this skill is invoked. The numbered sections describe concepts rather than operational steps to follow. | 2 / 3 |
Progressive Disclosure | All content is inlined in a single monolithic file with no references to supporting documents. The massive code examples for error handling, circuit breakers, performance optimization, and TDD could easily be split into separate reference files. No bundle files are provided to support this, and no navigation structure exists. | 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
844f68d
- 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.