agent-migration-plan

Agent skill for migration-plan - invoke with $agent-migration-plan

1.83x

Quality

17%

Does it follow best practices?

Impact

99%

1.83x

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-migration-plan/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 comprehensive but bloated catalog: it maps 16 commands to agent YAML definitions with useful templates, yet it is far too long, has no progressive disclosure or external references, and lacks validation checkpoints in its migration workflow. It reads as a generated reference dump rather than a focused, navigable skill.

Suggestions

Move the 16 per-agent definitions into a references/ file (e.g. references/agent-catalog.md) and keep SKILL.md as a concise overview plus the format template and migration steps.

Add explicit validation checkpoints to the Migration Steps (e.g. after converting each command, validate the agent YAML parses and tool restrictions match the original command), with a fix-and-retry loop.

Trim repeated boilerplate: define the common 'restricted: Bash/Write/Edit' pattern once instead of restating it for every agent.

Dimension	Reasoning	Score
Conciseness	The body is ~750 lines of near-identical YAML boilerplate repeated for 16 agents, restating the same responsibilities/capabilities/tools structure with minimal added guidance per agent; it is padded with redundant context rather than leaning on what Claude already knows.	1 / 3
Actionability	It provides concrete, copy-paste-ready YAML templates and a definition format, which is more than abstract description, but the bulk is reference listing rather than executable commands/code Claude would run, so key actionable detail is incomplete.	2 / 3
Workflow Clarity	The 'Migration Steps' section lists a 5-step sequence, but this batch/destructive migration has no validation checkpoints or feedback loops between steps; per the rubric this caps workflow_clarity at 2.	2 / 3
Progressive Disclosure	Everything lives in one monolithic SKILL.md with no bundle files in references/scripts/assets and no one-level-deep navigation; the 16 agent definitions are all inline, which matches the 'monolithic wall of text' anchor.	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 a thin placeholder: it labels the skill and exposes an invocation token but names no concrete capabilities and provides no usage triggers. It fails the 'what and when' completeness bar and reads as machine-generated boilerplate rather than user-facing guidance.

Suggestions

Replace the description with concrete actions, e.g. 'Maps .claude/commands to agent definitions with roles, capabilities, tool restrictions, and triggers. Use when migrating a claude-flow command system to agents.'

Add explicit 'Use when...' triggers using natural phrases a user would actually say (e.g. 'convert commands to agents', 'migrate claude-flow commands').

Drop the invocation token '$agent-migration-plan' from the description; keep it concise and in third person.

Dimension	Reasoning	Score
Specificity	The phrase 'Agent skill for migration-plan' names no concrete actions, only a domain label; this matches the 'vague or no actions' anchor.	1 / 3
Completeness	It states a weak 'what' ('migration-plan') with no 'Use when...' clause or equivalent trigger, so the 'when' is entirely missing rather than merely implied.	1 / 3
Trigger Term Quality	The only term is the invocation token '$agent-migration-plan', which is a system handle rather than a natural phrase a user would say; it is overly generic/technical jargon, not the level-2 bar.	1 / 3
Distinctiveness Conflict Risk	'migration-plan' is somewhat specific and the invocation token is distinctive, but the description is generic enough that it could overlap with other migration/planning skills; it is not a clear, conflict-free niche.	2 / 3
	Total	5 / 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 (751 lines); consider splitting into references/ and linking	Warning

	Total	15 / 16 Passed

Repository: ruvnet/ruflo
Path: .agents/skills/agent-migration-plan/SKILL.md
Commit: 26c35b5

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