Skip to content
skills

Development Guidelines

Skill Layout

Section titled “Skill Layout”

Every skill lives in skills/<name>/ and must include SKILL.md.

skills/
  my-skill/
    SKILL.md
    scripts/
    references/
    assets/

Keep skill names kebab-case and match the name field in frontmatter to the directory name. scripts/validate.sh enforces this.

Writing Skills

Section titled “Writing Skills”
  • Keep SKILL.md focused on trigger conditions and workflow.
  • Put long reference material under references/.
  • Put deterministic helpers under scripts/.
  • Put templates, images, and copied output assets under assets/.
  • Use canonical IDs like vd:cook or vd:docs when referring to skills in docs.

Source: skills/skill-management/SKILL.md, scripts/validate.sh.

Local Commands

Section titled “Local Commands”
Terminal window
bash scripts/new-skill.sh my-new-skill
bash scripts/validate.sh
bash scripts/check-release-versions.sh
vd list
vd doctor
(cd docs && npm run build)   # docs site

Release Hygiene

Section titled “Release Hygiene”

Use Conventional Commits. Focus scopes on the changed component:

feat(scout): add external mode
fix(skill-management): update vd-cli module path
docs: migrate site to astro starlight

Documentation Rules

Section titled “Documentation Rules”

Canonical shared docs live in README.md and docs/. Project journals and one-off reports should stay out of docs/ so the published site remains durable.

Public docs should cite the files they describe. If a claim cannot be traced to source, either remove the claim or add the missing source.