validate-skill

Validate the structure and completeness of an AI agent skill following this repository's authoring conventions.

When to Use

• User wants to check if a skill directory has all required files
• User wants to verify SKILL.md frontmatter is correct
• User wants to confirm references/INDEX.md exists and is valid
• User wants to check boundary tables reference all other skills
• User asks "is this skill complete?" or "does this skill follow conventions?"

Do not force this skill onto skill creation tasks — use skill-author for creating new skills. Do not use this skill for HarmonyOS development content validation — use the domain skills instead.

Boundary with Other Skills

This skill covers structural validation, not content authoring or development tasks:

Workflow (Follow Strictly)

1. Check Directory Structure

Verify the skill directory contains:

• SKILL.md (required)
• references/ directory (required for offline-doc skills; exempt for online-type skills like harmony-fetch and meta skills like skill-author/validate-skill itself)
• references/INDEX.md (required whenever references/ exists)
• assets/ directory (optional, but if code examples are referenced in SKILL.md, it must exist)
• scripts/ directory (optional, only if SKILL.md references utility scripts)

2. Validate SKILL.md Frontmatter

Check the YAML frontmatter contains:

• name: matches the directory name exactly
• description: comprehensive trigger condition with keywords, error codes, API names, and scenarios
• Optional fields (version, license, metadata) are correctly formatted if present

Description quality check: The description should be detailed enough that the agent activates this skill for all relevant scenarios. Check for:

• Specific error codes or messages (if applicable)
• API names, decorators, classes (if applicable)
• Scenario keywords and synonyms
• Related concepts

3. Validate SKILL.md Body Sections

Check the body contains these sections in order:

• # Skill Name — title with one-line purpose statement
• ## When to Use — bullet list of activation scenarios
• ## Boundary with Other Skills — table with three columns: Issue Type | Cross-reference Skill | Boundary
• ## Workflow (Follow Strictly) — numbered steps

Boundary table check: The table must reference the repo skills where boundaries exist. The current domain-skill inventory is listed in the repo root README.md (Skills table) — keep that table as the single source of truth instead of hardcoding names here. Every skill referenced in a boundary table must exist as a directory in this repo (a reference to a skill that is only installed user-side, e.g. an old standalone name, is a defect). If a boundary doesn't apply, it should be omitted (not forced).

4. Validate references/INDEX.md

Check INDEX.md contains:

• > **Must read first** note at the top
• ## Document Roles table listing every doc file and its role
• ## Reading Paths by Scenario table mapping scenarios to required reading
• Each file listed in Document Roles actually exists in references/

5. Validate Reference Documents

For each doc in references/ (excluding INDEX.md), the source header must use one of the AGENTS.md-sanctioned forms:

• Standard: > **上游 URL**: ... and > **抓取时间**: YYYY-MM-DD
• Enhanced: > 来源：官方《标题》(URL)（版本号），核实于 YYYY-MM-DD (adds verified doc version)
• Aggregated form (catalog-level URL, e.g. 聚合自 ... catalog) is acceptable for skills that merge many leaf docs
• Original-authored content (no upstream, e.g. curated error catalogs) and online-type skills (no offline references/) are exempt — see AGENTS.md

6. Validate Code Examples (if assets/ exists)

• Each .ets file has BAD vs GOOD pattern with clear labels
• Each file is minimal and focused on one error/fix

7. Check Boundary Consistency

For each other skill in the repo, check that its ## Boundary with Other Skills table references this skill where appropriate. If this skill is new, the other skills' boundary tables may need updating. Two directions must hold:

• Forward: this skill's boundary table only references skills that exist in the repo.
• Reverse: every other skill whose scope overlaps this one references it back.

8. Scriptable Checks (preferred before manual review)

Run these as a script when available — they catch the most common defects mechanically:

• Frontmatter name equals the directory name
• Every skill name referenced in SKILL.md/INDEX.md body has a matching repo directory
• Every relative file link in SKILL.md / INDEX.md resolves to an existing file
• INDEX.md "Document Roles" lists only files that exist under references/
• Every references/*.md has a source header (standard or enhanced form, see AGENTS.md)
• Every assets/*.ets contains BAD and GOOD markers

9. Report Findings

Summarize the validation results as a checklist:

## Validation Report: <skill-name>

### Structure
- [x] SKILL.md exists
- [x] references/ directory exists
- [x] references/INDEX.md exists
- [ ] assets/ directory exists (referenced in SKILL.md but missing)

### Frontmatter
- [x] name matches directory
- [x] description is comprehensive
- [ ] version field is missing

### Body Sections
- [x] When to Use section present
- [x] Boundary table present and references other skills
- [ ] Workflow section is missing

### INDEX.md
- [x] Must read first note present
- [x] Document Roles table complete
- [x] All listed files exist

### Reference Documents
- [x] All docs have source URL and timestamp
- [ ] 03-topic.md is missing fetch timestamp

### Boundary Consistency
- [ ] arkts-helper boundary table does not reference this skill

List any issues found and suggest fixes.