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