Agent Skills

Agent skills are reusable Markdown instructions stored inside a plugin:

plugins/<plugin>/skills/<skill-name>/SKILL.md

Available skills

Skill	Purpose
docs-research	Research official documentation and produce implementation checklists
skill-guide	Design, organize, and validate reusable skills
create-skill	Author a new reusable skill
durable-plans	Maintain task journals, verification evidence, and session recovery

Install an individual skill without its plugin's agents, commands, or hooks:

gh skill install mehdihadeli/agent-toolkit durable-plans
npx skills add mehdihadeli/agent-toolkit --skill durable-plans

Choose one installer. gh skill requires GitHub CLI 2.90+; npx skills requires Node.js and npm. See skills-only installers for agent selection, install scopes, version pinning, and installation boundaries.

Required structure

SKILL.md starts with YAML frontmatter containing:

---
name: example-skill
description: Explain what skill does and when host should activate it.
---

The name must match its directory name. The description must describe concrete activation conditions, not only topic keywords.

Skill design

Keep core instructions short and deterministic. Put large examples or reference material in nearby references/ or assets/ files. A skill should state:

Required inputs and context.
Ordered work steps.
Boundaries and unknowns.
Validation criteria.
Expected output.

Current examples:

Evaluation

Add a Vally evaluation under tests/<plugin>/vally/ for behavior that can be exercised through a prompt. Run vally lint . and a focused vally eval before publishing.

Optional executable support

A skill may include deterministic scripts when instructions alone are not enough:

plugins/<plugin>/skills/<skill-name>/
├── SKILL.md
├── references/       # optional supporting material
├── scripts/          # optional production scripts
└── package.json      # only when Node tooling needs its own dependencies

tests/<plugin>/scripts/<skill-name>/  # script tests and fixtures

Use .mjs by default for skill and plugin-management scripts. Use Python for domain-specific document or image processing when its libraries are stronger. Use C# for MCP servers, standalone agents, hosted workflows, Copilot SDK, or substantial .NET integrations. Keep shared repository tooling in the root package.json; do not add a package file to instruction-only skills.

Script tests belong under tests/<plugin>/scripts/ and should test the executable contract directly. Keep them separate from Vally prompt evaluations and Waza trigger tests.