agent-refinement

Agent skill for refinement - invoke with $agent-refinement

1.23x

Quality

13%

Does it follow best practices?

Impact

96%

1.23x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./.agents/skills/agent-refinement/SKILL.md

Quality

Content

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 generic software engineering tutorial rather than actionable agent guidance. It explains well-known patterns (TDD, circuit breakers, error hierarchies, complexity reduction) that Claude already understands, consuming significant token budget without adding project-specific value. The content would benefit from being reduced to a concise checklist of refinement steps with project-specific conventions, moving examples to separate reference files.

Suggestions

Reduce the body to under 50 lines: a concise refinement checklist (what to check, in what order, when to stop) rather than teaching TDD and design patterns Claude already knows.

Remove generic code examples (circuit breaker, error hierarchy, authentication service) or move them to separate reference files if they represent project-specific patterns.

Add explicit validation checkpoints and exit criteria: how does the agent know refinement is complete? What metrics or test results trigger completion?

If the skill is meant to be project-specific, include references to actual project files, test commands, and coding conventions rather than textbook examples.

Dimension	Reasoning	Score
Conciseness	Extremely verbose at ~350+ lines. Explains fundamental concepts Claude already knows (TDD red/green/refactor, circuit breakers, error hierarchies, retry logic, cyclomatic complexity). The examples are generic software engineering patterns, not project-specific guidance. Most content could be removed entirely.	1 / 3
Actionability	The code examples are concrete and mostly executable TypeScript, which is good. However, they are generic textbook examples (authentication service, circuit breaker) not tied to any specific project or codebase. Claude wouldn't know when or where to apply these patterns without more context about the actual refinement task.	2 / 3
Workflow Clarity	The TDD phases (Red/Green/Refactor) provide a sequence, but there are no explicit validation checkpoints or feedback loops for the overall refinement process. The numbered sections under 'SPARC Refinement Phase' list activities but don't define when to stop iterating, how to verify improvements, or decision criteria for what to refine first.	2 / 3
Progressive Disclosure	Monolithic wall of text with no references to external files and no bundle files to support it. All content is inline — the error handling section, performance optimization, circuit breaker implementation, and quality metrics could each be separate reference files. The skill tries to be a comprehensive textbook rather than a concise overview.	1 / 3
	Total	6 / 12 Passed

Description

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 trigger terms, no 'when to use' guidance, and is so vague that it could conflict with virtually any skill involving iterative improvement. It reads more like a command reference than a skill description.

Suggestions

Define what 'refinement' means concretely — specify what is being refined (e.g., code, text, designs) and list the specific 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, such as 'Use when the user asks to improve, polish, iterate on, or refine code/text/output.'

Narrow the scope to a clear niche to avoid conflicts with other skills — e.g., 'Refines Python code for readability and performance' rather than generic 'refinement.'

Dimension	Reasoning	Score
Specificity	The description provides no concrete actions whatsoever. 'Refinement' is abstract and undefined — there is no indication of what is being refined or how.	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' with an invocation command, providing no functional or contextual information.	1 / 3
Trigger Term Quality	The only potentially useful term is 'refinement,' which is vague and not a natural keyword users would say. '$agent-refinement' is a command invocation, not a trigger term. No natural language keywords are present.	1 / 3
Distinctiveness Conflict Risk	'Refinement' is extremely generic and could apply to code refinement, text refinement, image refinement, or any iterative improvement process. This would easily conflict with many other skills.	1 / 3
	Total	4 / 12 Passed

Validation

90%

Warnings & errors only

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: 28c81c0

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

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.