umbraco-skill-validator

name	umbraco-skill-validator
description	Validate links and references in SKILL.md files using deterministic scripts
allowed-tools	Bash, Read, Glob, Task, AskUserQuestion, Edit

Skill Content Validator

Validates all SKILL.md files in the repository for broken links, missing references, and invalid paths.

What This Skill Does

1. Runs deterministic validation script - Fast, consistent checking of all links
2. Generates structured report - JSON output with all issues found
3. Spawns fixer subagent - AI-powered fix suggestions for issues
4. Presents fix plan - Diff-style changes for approval
5. Executes approved fixes - Only applies changes user approves

Validation Checks

Check Type	Description
External URLs	HTTP HEAD request to verify accessibility
Skill references	Verify referenced skills exist (e.g., umbraco-dashboard)
Internal links	Check relative paths resolve (e.g., patterns/foo.md)
File paths	Verify Umbraco-CMS paths via GitHub API if not local
Import paths	Check @umbraco-cms/backoffice/* imports are valid

Running the Validator

Via Slash Command

/validate-skills

Via Script Directly (CI/CD)

cd .claude/skills/umbraco-skill-validator/scripts
npm install
npm run validate

Report Format

The script outputs JSON that gets formatted as:

# Skill Validation Report

## Summary
- Skills scanned: 25
- Issues found: 3
- Auto-fixable: 2

## Issues by Skill

### `umbraco-dashboard`
| Line | Type | Issue | Status |
|------|------|-------|--------|
| 45 | Broken URL | [example-broken-url] returns 404 | :x: |

### `umbraco-tree`
| Line | Type | Issue | Status |
|------|------|-------|--------|
| 72 | Missing skill | [example-missing-skill] not found | :x: |

Fix Plan Format

When issues are found, the fixer subagent generates:

# Fix Plan

## Fix 1: Update broken URL
**File:** plugins/.../umbraco-dashboard/SKILL.md
**Line:** 45
**Action:** Replace with current documentation URL

- [Dashboard docs][old-url]
+ [Dashboard docs][new-url]

## Approval
- [ ] Fix 1: Update broken URL
- [ ] Fix 2: ...

Link Patterns Detected

External URLs

https://docs.umbraco.com/...
https://github.com/umbraco/...

Skill References

`umbraco-dashboard`
`umbraco-workspace`

Internal Pattern Links

[Pattern Name](patterns/pattern-name.md)
[Example](examples/example-name/)

File Paths

/Umbraco-CMS/src/Umbraco.Web.UI.Client/...
src/packages/core/...

Import Paths (in code blocks)

import { ... } from '@umbraco-cms/backoffice/notification';

Workflow Instructions

When this skill is invoked:

1. Run the validation script

   cd .claude/skills/umbraco-skill-validator/scripts
   npx tsx validate-links.ts
   

2. Read the JSON output from stdout or validation-report.json

3. Format as markdown report using the template above

4. If issues found, spawn the skill-content-fixer agent:

   • Pass the JSON report as context
   • Request fix suggestions with diffs

5. Present fix plan to user with AskUserQuestion

6. Execute only approved fixes using Edit tool

Edge Cases

• Rate limiting: Script batches URL checks with 100ms delays
• Redirects: Reported as warnings with new URL suggestion
• Missing Umbraco-CMS: Falls back to GitHub API
• Timeouts: 5 second timeout per URL request
• Large repos: Processes files in batches of 10