Name: agent-refinement
Rating: 54.400000000000006 (1 reviews)
Author: ruvnet

Blog Docs Log in Get started

agent-refinement

Agent skill for refinement - invoke with $agent-refinement

1.23x

Quality

31%

Does it follow best practices?

Impact

96%

1.23x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/agent-refinement/SKILL.md

The canonical home for this skill is agent-refinement in ruvnet/claude-flow

Quality

Content

38%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is an over-long tutorial that re-teaches familiar TDD and error-handling patterns with illustrative but non-executable code, lacks validation checkpoints in its workflows, and is a monolithic file with no progressive disclosure. It is more of a concept primer than a lean, actionable skill.

Suggestions

Cut the tutorial prose and shrink the illustrative TypeScript to minimal, self-contained, copy-paste-runnable snippets; assume Claude knows TDD and dependency injection.

Add explicit validation checkpoints to the workflow, e.g. after Green: 'Run npm test; only proceed to Refactor when all tests pass; if a test fails, fix the implementation before continuing'.

Move the CircuitBreaker, retry-decorator, and error-hierarchy reference implementations into separate files under references/ or scripts/ and link to them from a concise overview, so SKILL.md stays a lean entry point.

Dimension	Reasoning	Score
Conciseness	At ~529 lines the body is dominated by long tutorial-style TypeScript samples (AuthenticationService, CircuitBreaker, retry decorator) that teach TDD and error-handling concepts Claude already knows, fitting the 'noticeably verbose; several unnecessary explanations or padded sections' anchor.	2 / 5
Actionability	It provides concrete TypeScript examples, but they are illustrative templates relying on undefined helpers (hash, createMockRepository, verifyPassword, sanitizeUser, SESSION_DURATION, AuthConfig, EventBus), so they are not copy-paste executable — matching 'some concrete guidance but incomplete; missing key details'.	3 / 5
Workflow Clarity	A Red→Green→Refactor sequence is present, but there are no explicit validation checkpoints or feedback loops (e.g. 'run npm test; only proceed if green') for the refactoring/destructive operations, and the guidelines cap workflow clarity at 3 when validation is missing.	3 / 5
Progressive Disclosure	The skill is a monolithic 529-line file with no references/, scripts/, or assets/ bundle and no external references, while substantial implementable material (CircuitBreaker, retry decorator, error hierarchy) that belongs in separate files is inlined, matching the 'content that clearly belongs in separate files is inlined' anchor.	2 / 5
	Total	10 / 20 Passed

Description

25%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is vague and non-actionable, naming only a broad domain ('refinement') plus an invocation token without stating concrete capabilities or a use-when trigger. It fails to distinguish the skill from other code-quality skills.

Suggestions

Replace 'Agent skill for refinement' with concrete actions, e.g. 'Refactors, optimizes, and hardens code through TDD red/green/refactor cycles, performance profiling, and error-handling improvements'.

Add an explicit 'Use when...' clause naming natural user triggers such as 'refactor this code', 'optimize slow functions', 'improve test coverage', or 'harden error handling'.

Drop the '$agent-refinement' invocation token from the description; keep the description focused on what the skill does and when to use it, not on how it is invoked.

Dimension	Reasoning	Score
Specificity	The phrase 'Agent skill for refinement' names the domain but lists no concrete actions (testing, optimization, refactoring are absent), matching the anchor that names the domain with minimal or generic actions.	2 / 5
Completeness	It gives only a vague 'what' ('Agent skill for refinement') and entirely omits any 'when'/Use-when clause, which per the guidelines caps completeness at 3; the vague what without when places it at 2.	2 / 5
Trigger Term Quality	Only 'refinement' and the invocation token '$agent-refinement' appear; these are jargon/technical identifiers rather than the natural phrases a user would say ('refactor', 'optimize', 'improve code'), fitting one-or-two generic keywords missing natural phrases.	2 / 5
Distinctiveness Conflict Risk	'Refinement' is very broad and would overlap with many code-quality, refactoring, and testing skills, matching the anchor for very broad with high overlap risk.	2 / 5
	Total	8 / 20 Passed

Validation

93%

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 — 15 / 16 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	15 / 16 Passed

Repository: ruvnet/ruflo
Path: .agents/skills/agent-refinement/SKILL.md
Commit: fa13ee4

Reviewed: about 8 hours 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.