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 findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.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.

The body is a verbose, monolithic dump of generic TDD/performance/error-handling patterns Claude already knows, with no file-based progression and no validation checkpoints in its workflows. Concrete code examples partially redeem actionability, but conciseness and progressive disclosure are weak.

Suggestions

Cut the tutorial-style explanations of TDD, circuit breakers, and cyclomatic complexity; keep only skill-specific, non-obvious guidance and lean executable snippets.

Add validation/feedback checkpoints to the TDD and refinement workflows (e.g. 'run npm test; only proceed to refactor when green').

Move large reference code (error hierarchy, CircuitBreaker, coverage config) into separate reference files and link to them one level deep, removing the stray duplicate YAML block at the top of the body.

Dimension	Reasoning	Score
Conciseness	The body is ~525 lines of large TypeScript/Jest dumps explaining TDD red/green/refactor, circuit breakers, and cyclomatic complexity — concepts Claude already knows — padded with full example classes. This matches score 1 'Verbose; explains concepts Claude knows; padded with unnecessary context'. It is not score 2 because the bulk is teaching known concepts rather than tight, skill-specific guidance.	1 / 3
Actionability	The examples are real, mostly executable TypeScript rather than pseudocode (e.g. the CircuitBreaker class, retry decorator), but key helpers like sanitizeUser, generateToken, verifyPassword, and createSession are referenced yet never defined, leaving guidance incomplete. This matches score 2 'Some concrete guidance but incomplete; missing key details'; it is not score 3 because the code is not copy-paste complete, and not score 1 because it is concrete code rather than vague direction.	2 / 3
Workflow Clarity	The TDD section sequences Red -> Green -> Refactor phases with numbered headings, but there are no validation checkpoints (e.g. 'run the suite and only proceed when green') and the error/perf sections lack feedback loops. Per the guideline, missing validation/feedback loops for iterative risky work caps clarity at 2.	2 / 3
Progressive Disclosure	The skill is a single monolithic file with no bundle files (references/, scripts/, assets/ absent) and no external references or navigation; large blocks that could live in separate files are inline, and a stray second YAML frontmatter block sits at the top of the body. This matches score 1 'Monolithic wall of text; poor organization'.	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.

The frontmatter description is too vague to function as a skill description: it names no concrete capabilities, provides no natural trigger terms, and gives no 'use when' guidance. It reads as an invocation stub rather than a discoverable description.

Suggestions

Replace the description with concrete actions, e.g. 'Iteratively improve code quality through test-driven development, refactoring, performance tuning, and error-handling improvements.'

Add an explicit trigger clause: 'Use when the user asks to refactor, optimize, harden error handling, or improve test coverage of existing code.'

Reference the SPARC Refinement phase niche explicitly to reduce overlap with generic refactoring/testing skills.

Dimension	Reasoning	Score
Specificity	The description 'Agent skill for refinement - invoke with $agent-refinement' names only the abstract domain 'refinement' and lists no concrete actions, matching the score-1 anchor 'Vague or no actions; abstract language' (e.g. 'Helps with documents'). It is not score 2 because no specific actions (e.g. refactor, optimize, write tests) are named at all.	1 / 3
Completeness	It states a weak 'what' ('Agent skill for refinement') and entirely omits 'when' — there is no 'Use when...' clause, so it fails both halves. Per the guideline, a missing explicit trigger clause caps completeness at 2; here 'what' is also vague, placing it at score 1.	1 / 3
Trigger Term Quality	The only trigger guidance is the invocation token '$agent-refinement' plus the word 'refinement'; there are no natural keywords a user would say (refactor, optimize, improve code, fix tests), matching score 1 'No natural keywords; technical jargon or overly generic'. It does not reach score 2 because there are no common user-facing variations present.	1 / 3
Distinctiveness Conflict Risk	'refinement' is generic and would overlap with many skills (refactoring, optimization, testing, review skills); the actual frontmatter description never mentions the SPARC niche. This matches score 1 'Very generic; would conflict with many skills'. It is not score 2 because no sufficiently specific scope is stated in the description.	1 / 3
	Total	4 / 12 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/claude-flow
Path: .agents/skills/agent-refinement/SKILL.md
Commit: 26c35b5

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