Skip to content

Agent Skills

Technical reference for the open Agent Skills specification and the authoring practices that keep skills portable, discoverable, and cheap to load.

This skill covers the format itself. For VS Code Copilot placement, instructions, prompts, agents, and hooks, use copilot-customization. For skills published from this repository, also apply the Skill Contract and Frontmatter Contract.

When to Use

  • Creating or revising a SKILL.md directory.
  • Checking name / description frontmatter against the spec.
  • Splitting a monolithic skill into references/, scripts/, or assets/.
  • Improving trigger quality of a skill description.
  • Validating skill layout before FastMCP or client discovery.
  • Researching a library or protocol before writing or changing skill content.

Load Map

Open only the reference that matches the current task:

  • Official source index: source map
  • Docs-then-source research before drafting skill content: research
  • Directory layout, frontmatter fields, progressive disclosure, file references, validation: specification
  • Scope, context budget, control calibration, instruction patterns: authoring
  • Trigger wording and description evals: descriptions
  • One-off commands and bundled scripts/: scripts
  • Output evals and iteration: evaluation

Canonical Shape

A skill is a directory whose name equals frontmatter name, containing at least SKILL.md:

skill-name/
    SKILL.md
    scripts/       # optional executable code
    references/    # optional on-demand docs
    assets/        # optional templates and static files

SKILL.md is YAML frontmatter plus Markdown instructions. Agents load name and description for every skill at discovery time, the full body only after activation, and supporting files only when a path is referenced.

In this repository:

  1. Skills live under src/jsl_mcp/docs/skills/<skill-id>/.
  2. Frontmatter is only name and description.
  3. Prefer references/ unless the skill needs executable or static resources.
  4. Directory name, URI id, and name must match and start with a letter.

Frontmatter Invariants

Required by the specification:

Field Constraint
name 1–64 chars; a-z, 0-9, -; no leading, trailing, or consecutive hyphens; equals parent directory name
description 1–1024 chars; what the skill does and when to use it; keyword-rich for discovery

Optional in the specification, omitted here: license, compatibility, metadata, experimental allowed-tools.

description is the entire discovery surface. Imperative "Use when..." phrasing, user intent (not implementation), and near-miss boundaries outperform vague summaries.

Authoring Invariants

  1. Keep SKILL.md under 500 lines and about 5,000 tokens. Move depth into focused supporting files.
  2. Link supporting files from SKILL.md with paths relative to the skill root. Stay one level deep; do not chain references.
  3. Tell the agent when to load each file. A labeled load map beats "see references/".
  4. Put only what the agent would get wrong without the skill: conventions, defaults, gotchas, fragile sequences.
  5. Scope one coherent unit of work. Too narrow forces multi-skill loads; too broad blunts triggering.
  6. Prefer procedures that generalize over instance-specific answers.
  7. Give a default with an escape hatch rather than a menu of equal options.
  8. Be prescriptive only where the sequence is fragile; otherwise state the purpose and let the agent adapt.
  9. Keep gotchas in SKILL.md when the agent will not recognize the trigger in time to open a reference.

Validation

  1. name equals the directory name.
  2. Frontmatter is valid YAML between --- markers; quote descriptions that contain colons.
  3. Every supporting file that matters is linked from SKILL.md with a load condition.
  4. Relative links resolve from the skill root.
  5. Optional: skills-ref validate on the skill directory.

Repository publication is through FastMCP as skill://<skill-id>/SKILL.md, skill://<skill-id>/_manifest, and supporting paths. Only the main file and manifest appear in resources/list.

Output Contract

Return:

  1. Whether the skill conforms to the specification and, if in this repo, the local contracts.
  2. The smallest frontmatter, body, or layout change required.
  3. Which supporting file to load next, if any.
  4. Source citations for spec-level claims (inline Markdown links).