skill-md-validation

name	skill-md-validation
description	Validates SKILL.md packages and cursor-rule files against what Agent Skill Sync indexes and syncs from GitHub. Use when changing RepoService catalog logic, SyncEngine package writes, or troubleshooting missing skills in the Skill Manager.
disable-model-invocation	true

SKILL.md validation (GitHub source)

Official spec reference: agentskills.io specification.

What counts as a skill package

In RepoService.listSkillsInRepo, a skill package is any directory under the resolved skills root that contains a blob path ending in SKILL.md (case-sensitive filename). All blobs under that directory are collected into skillFiles for sync.

What counts as a cursor-rule

Standalone blobs under the skills root with extensions .md, .mdc, .yaml, .yml that are not inside a skill-package directory become skillType: "cursor-rule".

Frontmatter parsing

parseSkillMdFrontmatter reads the first YAML block between --- lines. Supported subset:

• Top-level scalars: name, description (simple key: value lines).
• Nested metadata: block with two-space-indented keys (string values only)—used for version and category when present.
• Optional metadata.triggers: block with four-space-indented keys: languages, files, dependencies, extensions, keywords (comma-separated lists; scoped npm names may be quoted), and generalPurpose (true / false). Lists are lowercased when stored except file path tokens.

It does not load a full YAML parser; keep manifests within that subset or metadata may be ignored.

Manifest → SkillMeta

From fetchSkillManifests / standalone cursor-rule enrichment:

Field	Source
name	Frontmatter name, else path-derived
description	Frontmatter description
version	metadata.version, else short SHA
category	metadata.category, else path-derived
path	Package directory path in repo
skillType	Always "skill"
skillFiles	All blob paths under the package dir
triggers	Parsed metadata.triggers when present

Workspace writes

SyncEngine.syncSkillPackage fetches each listed path and writes via writeSkillPackageFile under .cursor/skills/<normalized-name>/. Names are normalized with normalizeSkillName (lowercase, hyphen-safe).

Cursor-rules use writeSkillFile → .cursor/rules/<name>.mdc.

Skills root resolution

RepoService picks the first existing candidate: repo root (if it looks like a skills root), then skills, .skills, rules, .cursor/rules.

Custom registry note

RegistryService currently maps API skills to cursor-rule only (single-file content). Package semantics apply to GitHub indexing unless registry support is extended.