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

Optimize this skill with Tessl

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

Quality

Discovery

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 essentially a stub that provides only an invocation command and a generic label. It completely lacks concrete actions, natural trigger terms, explicit usage guidance, and domain specificity. It would be nearly impossible for Claude to correctly select this skill from a pool of available skills.

Suggestions

Add concrete actions describing what the skill does, e.g., 'Generates step-by-step migration plans for database schema changes, API version upgrades, or cloud infrastructure transitions.'

Add an explicit 'Use when...' clause with natural trigger terms, e.g., 'Use when the user asks about migrating databases, upgrading systems, planning a migration strategy, or moving between platforms.'

Specify the domain of migration (database, cloud, code framework, etc.) to reduce ambiguity and conflict risk with other skills.

Dimension	Reasoning	Score
Specificity	The description contains no concrete actions whatsoever. 'Agent skill for migration-plan' is entirely vague—it doesn't describe what the skill actually does (e.g., generate migration plans, analyze database schemas, etc.).	1 / 3
Completeness	The description fails to answer both 'what does this do' and 'when should Claude use it'. There is no 'Use when...' clause and no explanation of capabilities. It only provides an invocation command.	1 / 3
Trigger Term Quality	The only potentially relevant term is 'migration-plan', which is a hyphenated technical identifier rather than a natural keyword a user would say. There are no natural language trigger terms like 'migrate', 'database migration', 'upgrade path', etc.	1 / 3
Distinctiveness Conflict Risk	The term 'migration-plan' is ambiguous—it could refer to database migrations, cloud migrations, code migrations, data migrations, or even physical relocations. Without specificity, it risks both false positives and being overlooked for relevant queries.	1 / 3
	Total	4 / 12 Passed

Implementation

14%

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

This skill is an extremely verbose catalog of agent YAML definitions that repeats the same structural pattern ~20 times inline, consuming massive token budget without proportional value. The actual migration guidance (the stated purpose) is buried at the bottom in a vague 5-step list with no validation or executable commands. The content would be far more effective as a concise template + mapping table with agent definitions in separate files.

Suggestions

Extract all agent YAML definitions into a separate reference file (e.g., AGENT_CATALOG.md) and replace inline blocks with a summary table mapping command → agent name → key capabilities

Expand the Migration Steps section with executable commands (e.g., `mkdir -p .claude/agents/coordination`), concrete file creation examples, and explicit validation checkpoints after each step

Add a feedback loop for migration validation: how to test that an agent activates correctly, how to verify no functionality was lost, and how to rollback if issues are found

Reduce the SKILL.md to under 100 lines: one template example, the mapping table, the detailed migration workflow, and links to the full agent catalog

Dimension	Reasoning	Score
Conciseness	Extremely verbose at 500+ lines, mostly repetitive YAML blocks that follow the same pattern. The document explains obvious concepts (what agents do, what tool restrictions mean) and could be reduced to a template + table mapping commands to agents. Most content is boilerplate that Claude could generate from a concise specification.	1 / 3
Actionability	The YAML agent definitions are concrete and structured, providing specific tool names, trigger patterns, and role assignments. However, the migration steps themselves (section 4) are vague ('Create directory structure', 'Test agent interactions') with no executable commands or concrete examples of how to actually perform the migration.	2 / 3
Workflow Clarity	The migration steps in section 4 are a brief 5-item list with no validation checkpoints, no error recovery, and no verification that migration succeeded. For a destructive operation like system migration, this lacks the necessary feedback loops and explicit validation steps. The monitoring section lists metrics but provides no concrete way to measure them.	1 / 3
Progressive Disclosure	This is a monolithic wall of text with 20+ nearly identical YAML blocks inlined. The agent definitions should be in separate files or a reference document, with the SKILL.md providing just the migration workflow, a template, and links to the full agent catalog. No references to external files for detailed content.	1 / 3
	Total	5 / 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 (751 lines); consider splitting into references/ and linking	Warning

	Total	10 / 11 Passed

Repository: ruvnet/ruflo
Commit: 398f7c2

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.