agent-migration-plan

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

1.83x

Quality

—

Does it follow best practices?

Impact

99%

1.83x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Quality

Content

50%

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 well-structured but monolithic 750-line catalog mapping commands to agent YAML definitions, plus implementation guidelines. It provides reusable YAML templates but lacks executable migration commands, validation feedback loops for the batch migration, and any external reference files to split the heavy catalog.

Suggestions

Move the per-agent YAML catalog into a references file (e.g. references/agent-catalog.md) and keep SKILL.md as a concise overview with the format spec and a few representative examples, improving conciseness and progressive disclosure.

Add concrete, executable migration commands to the Migration Steps (e.g. directory creation, file conversion commands) rather than abstract directives.

Insert validation checkpoints into the migration workflow (e.g. validate each generated agent definition before proceeding, test agent handoffs, with a fix-and-retry loop), since this is a batch/destructive operation.

Dimension	Reasoning	Score
Conciseness	The body avoids lecturing on concepts Claude already knows, but ~750 lines are dominated by sixteen near-identical agent YAML blocks that could be templated from the format spec, so it is mostly efficient but could be substantially tightened rather than lean.	2 / 3
Actionability	Concrete YAML templates and the agent-definition format spec are copy-paste ready, but the actual 'Migration Steps' are abstract ('Convert each command to agent definition format', 'Update activation patterns') with no executable commands, fitting the 'some concrete guidance but incomplete' anchor.	2 / 3
Workflow Clarity	The Migration Steps provide a numbered sequence, but this batch/destructive migration has no validation checkpoints or validate-fix-retry feedback loops, which per the rubric caps workflow clarity at 2.	2 / 3
Progressive Disclosure	Content is organized into clear sections and categories, but the entire per-agent reference catalog is inlined in one 750-line SKILL.md with no bundle files (references/scripts/assets absent), so content that should be separate is inline.	2 / 3
	Total	8 / 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 bare auto-generated label that names the skill's domain but describes no capabilities, includes only a technical invocation token instead of natural triggers, and lacks any 'use when' clause. It is too generic to reliably guide when Claude should invoke this skill.

Suggestions

Replace the description with concrete actions, e.g. 'Converts .claude/commands definitions into agent-based YAML formats, mapping roles, capabilities, and tool restrictions. Use when migrating a claude-flow command system to agents or when the user asks to plan an agent rollout.'

Add natural-language trigger terms users would actually say (e.g. 'migrate commands to agents', 'agent rollout', 'convert commands') rather than the '$agent-migration-plan' invocation token.

Keep third-person voice but make the 'what' and 'when' explicit so it is distinguishable from other planning/migration skills.

Dimension	Reasoning	Score
Specificity	The description 'Agent skill for migration-plan' names a domain but lists no concrete actions or verbs describing what the skill does, matching the vague/no-actions anchor ('Helps with documents') rather than the action-naming score-2 anchor.	1 / 3
Completeness	It states neither concrete capabilities ('what') nor any 'use when' guidance ('when'); both are missing or very weak, which is below the score-2 anchor that at least names actions.	1 / 3
Trigger Term Quality	The only trigger phrasing is 'invoke with $agent-migration-plan', which is technical invocation jargon rather than natural keywords a user would say, fitting the 'no natural keywords; technical jargon' anchor.	1 / 3
Distinctiveness Conflict Risk	'migration-plan' names a distinct domain giving a slight niche, but the generic framing and absence of distinct triggers means it could still overlap with other planning/migration skills, matching the 'somewhat specific but could overlap' anchor.	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/claude-flow
Commit: 8ae8752

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