| 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.
