CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

79

Quality

73%

Does it follow best practices?

Impact

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

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

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 an excellent skill description that is highly specific, includes explicit trigger terms, clearly answers both what and when, and occupies a distinct niche. The phased structure (Phase 1-3) adds clarity about the workflow. The only minor weakness is density — the description packs a lot of information which could slightly reduce quick scannability, but all content is substantive rather than filler.

DimensionReasoningScore

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' (Hugo docs IA moves with phases for aliases, link updates, fragment validation) and 'when' (explicit 'Triggers on:' clause with five specific trigger phrases). Also includes post-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 — scoped specifically to Hugo docs information-architecture migrations with a clear phased workflow (aliases, in-repo links, fragment validation). The combination of Hugo, IA migration, and PR-scoped link passes creates a very narrow niche 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 demonstrates strong workflow design with clear phasing, validation checkpoints, and feedback loops for a complex multi-step migration process. However, it is severely undermined by extreme verbosity—the same rules and constraints are repeated across multiple sections, inflating the token cost significantly. The skill would benefit greatly from consolidation of repeated rules, concrete examples (sample mapping tables, grep patterns, before/after alias blocks), and splitting reference material into separate files.

Suggestions

Consolidate repeated rules (No guessing, sweep scope, List 1/List 2 definitions, Modes scope) into single authoritative sections referenced by name, rather than restating them in every phase and procedure block.

Add concrete, copy-paste-ready examples: a sample old→new mapping table, example grep/rg commands with actual path patterns, and a before/after front matter block showing alias addition.

Split Conventions and Special Cases into a separate REFERENCE.md file, keeping only a brief summary and link in SKILL.md to reduce the main file's token footprint.

Remove the 'Agent: required procedure' numbered summary since it nearly duplicates the phase descriptions—or keep only the summary and make the phases into a referenced detail file.

DimensionReasoningScore

Conciseness

The skill is extremely verbose at ~400+ lines with extensive repetition of concepts across sections. The same rules (No guessing, sweep vs PR_SCOPE_FILES, List 1/List 2 distinction, Modes scope) are restated 4-6 times each. Many paragraphs explain procedural logic Claude could infer from a concise specification. The 'Agent: required procedure' section largely duplicates the phases themselves.

1 / 3

Actionability

The skill provides some concrete commands (git diff, docker buildx bake validate, rg for sweeps) and a clear phased structure, but most guidance is procedural prose rather than executable examples. There are no concrete examples of mapping tables, List 1/List 2 entries, actual grep patterns, or sample alias front matter edits—just descriptions of what to do abstractly.

2 / 3

Workflow Clarity

The multi-phase workflow is clearly sequenced (Phase 0 → 0.5 → 1 → 2 → 3 → Verification → review-changes) with explicit validation checkpoints (re-sweep after Phase 2, validate after Phase 3, Definition of Done criteria). Phase 3 includes a clear feedback loop (validate fragment → warn → ask again → repeat). The 'Agent: required procedure' section provides a numbered mandatory run order.

3 / 3

Progressive Disclosure

The skill mentions storing large mapping tables in reference.md and links to a scope helper script and the review-changes skill, which is good. However, the vast majority of content is inline in one monolithic file with no actual splitting—the 'Progressive disclosure (optional)' section acknowledges this but doesn't act on it. Content like Conventions, Special cases, and detailed phase instructions could benefit from being split into referenced files.

2 / 3

Total

8

/

12

Passed

Validation

100%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository
docker/docs
Reviewed

Table of Contents

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.