Inspect the workspace and identify the active skill layout before editing files.
Create/update <skill-root>/SKILL.md, <skill-root>/SPEC.md when required by change scope, and any bundled references/, scripts/, or assets/ beneath that root.
Default to .agents/skills/<name>/ when there is no stronger prior art.
If the workspace clearly uses a different canonical layout, follow that layout instead of forcing .agents/skills/.
Common established alternatives include:
skills/<name>/ when the workspace uses a canonical root skill tree
.claude/skills/<name>/ for project-scoped Claude skills
plugins/<plugin>/skills/<name>/ for plugin-scoped skills
another repository-managed skill root that is already established by neighboring skills or docs
If multiple plausible locations exist and inspection does not make the canonical target clear, ask the user before editing files.
Only apply repository-specific registration steps when the workspace conventions explicitly require them.
When a repository does maintain its own skill catalog, verify and update any required registration files such as:
The validator is a structural check. It should fail only for invalid skill format or missing referenced files. The size warning requires author judgment, not a machine gate.
Run:
bash
uv run scripts/quick_validate.py <path/to/skill-directory>
Use the skill-root-relative form above when running from the skill-writer directory.
If you must run the validator from another working directory, convert both paths to the correct relative path from that directory instead of introducing absolute or host-specific paths into the skill docs.
Confirm manually for authoring/generator skills:
transformed examples exist in references (happy-path, secure/robust, anti-pattern+fix)
synthesis coverage was considered and any gaps are explicit
selected example profile requirements are satisfied and reported
SPEC.md exists or was updated when the change creates a skill or materially changes intent, scope, evidence model, validation, or maintenance expectations
every bundled reference file is directly discoverable from SKILL.md
Confirm manually for integration/documentation skills:
focused references cover API surface, common use cases, known issues/workarounds, and version variance
reference file names fit the skill’s domain rather than a fixed template
SKILL.md and references/*.md avoid host-specific absolute filesystem paths
Confirm manually for skills that are expected to be portable by default:
bundled file references use skill-root-relative paths such as references/..., scripts/..., or assets/...
provider-specific path variables (for example ${CLAUDE_SKILL_ROOT}) should not be used; use skill-root-relative paths instead (e.g. scripts/foo.py, references/bar.md)
provider-specific behavior, if any, is labeled as compatibility guidance rather than the primary workflow
Review validator warnings for oversized SKILL.md files.
Do not add validators for skill class, coverage quality, SPEC shape, trigger quality, or other qualitative guidance.