tai/research/cap-protocol/agentskills-io-specification.md

Agent Skills specification

Metadata

Field	Value
Institute	Molodetz Institute — Research & Retrieval Division
Subject	cap-protocol
Document type	Source Dossier
Tier	1
Source title	Agent Skills specification
Source URL	https://agentskills.io/specification
Source publisher / author	Agent Skills project
Source type	standard
Source date (published)	Unknown — not stated
Date researched	2026-10-25
Researched by	tai (agent), model: Claude Sonnet 5, on behalf of retoor
Research method	direct page fetch
Confidence	High
Status	Active

Summary

The open SKILL.md format that tai's skill system already follows.

Key findings

• A skill is a directory with SKILL.md (YAML frontmatter plus Markdown) and optional scripts/, references/, assets/.
• name: 1-64 chars, lowercase alphanumerics and hyphens, no leading, trailing or consecutive hyphens, must match the directory name. description: 1-1024 chars, should say what the skill does and when to use it. Optional license, compatibility (max 500), metadata, experimental allowed-tools.
• Progressive disclosure: metadata about 100 tokens loaded at startup for all skills; instructions under 5000 tokens recommended on activation; resources on demand.
• Keep SKILL.md under 500 lines; keep file references one level deep from SKILL.md; validate with skills-ref validate.

Pros / strengths

Normative limits that a bundled tai skill can be checked against.

Cons / limitations / caveats

Describes format, not when a skill beats a tool.

Relevance to tai

Constraints for a bundled cap-agents skill: single-line description under 1024 chars (tai's own frontmatter subset needs single-line values), body under 5000 tokens, detail in references/.

Changelog

Date	Change
2026-10-25	Initial dossier created.