migrate-content-ia

Handle Hugo docs information-architecture moves: discover old vs new URLs, add front matter aliases (Phase 1), update in-repo links (Phase 2), interactive List 2 resolution and fragment validation (Phase 3; no guessing). Supports PR-scoped mapping plus whole-content sweeps for inbound links to that mapping, or a full-site follow-up. Triggers on: "IA migration", "redirects for moved pages", "fix links after content move", "PR-scoped link/anchor pass", "aliases for old URLs". After branch work, chain the review-changes skill (main...HEAD) before a PR. Agents must run the in-file required procedure and definition of done, not the phases alone in isolation.

Quality

73%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./.agents/skills/migrate-content-ia/SKILL.md

Quality

Discovery

100%

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 is a strong, well-crafted skill description that excels across all dimensions. It provides highly specific actions organized by phases, includes explicit trigger terms users would naturally use, and clearly delineates both what the skill does and when to use it. The Hugo-specific terminology and phased workflow structure make it highly distinctive and unlikely to conflict with other skills.

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions: discover old vs new URLs, add front matter aliases, update in-repo links, interactive List 2 resolution, fragment validation, PR-scoped mapping, whole-content sweeps. Very detailed and action-oriented.	3 / 3
Completeness	Clearly answers both 'what' (handle Hugo docs IA moves with phased approach including aliases, link updates, fragment validation) and 'when' (explicit 'Triggers on:' clause with five specific trigger phrases). Also includes workflow guidance about chaining the review-changes skill.	3 / 3
Trigger Term Quality	Includes explicit natural trigger terms: 'IA migration', 'redirects for moved pages', 'fix links after content move', 'PR-scoped link/anchor pass', 'aliases for old URLs'. These are phrases users would naturally say when needing this skill.	3 / 3
Distinctiveness Conflict Risk	Highly distinctive — targets a very specific niche of Hugo documentation information-architecture migrations with phased workflows. The combination of Hugo, front matter aliases, PR-scoped mapping, and fragment validation makes it unlikely to conflict with other skills.	3 / 3
	Total	12 / 12 Passed

Implementation

47%

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

This skill has excellent workflow clarity with well-defined phases, validation checkpoints, and feedback loops for a complex multi-step migration process. However, it is severely hampered by verbosity — the same rules (no guessing, sweep scope, List 1 vs List 2, PR-scoped vs full-site) are restated across multiple sections, inflating token cost significantly. Actionability would benefit from concrete examples (sample alias YAML, example grep commands, a sample List 1/List 2 table) rather than prose descriptions of what to do.

Suggestions

Cut repetition drastically: the 'No guessing' rule, sweep-vs-PR_SCOPE_FILES distinction, and List 1/List 2 definitions are each restated 3-5 times. State each once with a clear label, then reference by name.

Add concrete examples: show a sample old→new mapping table, a sample `aliases` front matter block, example rg/grep commands for the sweep, and a sample List 2 interactive exchange.

Extract the Conventions section and detailed phase instructions into separate bundle files (e.g., conventions.md, phases.md) and reference them from the main SKILL.md to reduce the monolithic wall of text.

Replace lengthy prose paragraphs with terse bullet lists or decision tables — e.g., the Modes section could be a 2-column table (PR-scoped vs Full-site) with one-line descriptions per row.

Dimension	Reasoning	Score
Conciseness	The skill is extremely verbose at ~400+ lines with extensive repetition. The same concepts (No guessing, sweep vs PR_SCOPE_FILES, List 1/List 2 distinction, Modes scope rules) are restated multiple times across sections. Many paragraphs explain procedural nuances that could be condensed into terse checklists. Claude does not need repeated reminders about not guessing or lengthy explanations of what 'PR-scoped' means across 4+ sections.	1 / 3
Actionability	The skill provides some concrete commands (git diff, docker buildx bake validate, rg for sweeps) and references specific file paths, but most guidance is procedural prose rather than executable examples. There are no concrete code snippets showing actual alias YAML, no example grep patterns for the sweep, and no example of what a List 1/List 2 table looks like. The phases describe what to do conceptually but lack copy-paste-ready templates.	2 / 3
Workflow Clarity	The multi-phase workflow (Phase 0 → 0.5 → 1 → 2 → 3 → Verification → review-changes) is clearly sequenced with explicit validation checkpoints (docker buildx bake validate, re-sweep after Phase 2, validation loop in Phase 3, Definition of Done). The feedback loop in Phase 3 (validate → warn → ask again → repeat) is well-defined, and the mandatory ordering is stated upfront with a numbered procedure.	3 / 3
Progressive Disclosure	The skill mentions storing large mapping tables in reference.md and references external files (CLAUDE.md, AGENTS.md, STYLE.md, COMPONENTS.md, scripts/scope-pr-files.sh), but no bundle files are provided. The content itself is monolithic — all phases, conventions, modes, and rules are inline in one very long file. The 'Progressive disclosure (optional)' section acknowledges this but only addresses the mapping table, not the conventions or detailed phase instructions that could be split out.	2 / 3
	Total	8 / 12 Passed

Validation

100%

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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: docker/docs
Commit: 2ea4a02

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.