Agent Skill Specification: [skill-name]

Design and review record for one Agent Skill: a folder with a SKILL.md file (YAML frontmatter plus Markdown instructions) and optional scripts/, references/ and assets/ directories that an agent loads on demand. It follows the open Agent Skills specification published at agentskills.io (checked 2026-10-22): required name and description fields, optional license, compatibility, metadata and experimental allowed-tools, progressive disclosure in three stages, and validation with the skills-ref reference library. It adds what the format leaves to you: trigger design, versioning, security review and evaluation. Replace every [bracketed] value and every row marked Example. Worked examples use a skill that drafts release notes from merged pull requests.

Document control

Approvals

Revision history

Contents

1. Purpose and scope
2. Activation and description design
3. Frontmatter
4. Directory layout
5. Instructions body
6. Scripts, references and assets
7. Progressive disclosure and context budget
8. Versioning and distribution
9. Security review
10. Evaluation
11. SKILL.md skeleton
12. Glossary and references

1. Purpose and scope

A skill packages procedural knowledge so an agent can apply it consistently. Prefer a skill when the instructions are long, are needed only for some tasks, or come with scripts and reference files. Prefer AGENTS.md (dev/agents-md) for short rules every task needs, and a tool (see Agent Tool and Function Catalogue, ai-data/tool-catalogue) when the capability is a single deterministic action with a stable interface.

2. Activation and description design

The description is read at startup for every installed skill and is the only signal the agent uses to decide activation. The specification asks it to say what the skill does and when to use it, and to include keywords that help agents recognise relevant tasks.

Draft description (Example, 187 characters, within the 1,024 limit):

description: Drafts release notes and CHANGELOG.md entries from merged pull requests between two git tags. Use when the user asks for release notes, a changelog entry, or what changed since a version.

Common pitfalls: a vague description ("Helps with releases") that never triggers; a greedy description that triggers on every git task; two skills with overlapping descriptions that compete.

3. Frontmatter

Rules for this organisation:

• Record the skill version in metadata (the specification has no version field); quote it so YAML keeps it a string.
• Use namespaced metadata keys (for example acme-owner) if skills are shared across organisations, to avoid key collisions.
• Use allowed-tools only after the security review in section 9, and pre-approve the narrowest pattern that works.

4. Directory layout

release-notes-writer/
├── SKILL.md                 # frontmatter + instructions (loaded on activation)
├── scripts/
│   └── collect_prs.py       # lists merged PRs between two tags as JSON
├── references/
│   ├── STYLE.md             # changelog style guide (loaded when writing)
│   └── CATEGORIES.md        # label to section mapping
└── assets/
    └── entry-template.md    # Markdown skeleton for one release entry

The specification requires only SKILL.md; scripts/, references/ and assets/ are recommended conventions. Reference files with relative paths from the skill root, and keep references one level deep from SKILL.md, so the agent never follows a chain of files to find a rule.

5. Instructions body

Planned structure of the SKILL.md body:

Writing rules:

• Use imperative steps ("Run", "Group", "Check"), one action each.
• Prefer a script for anything deterministic (listing, parsing, counting); keep model judgement for wording and grouping.
• Give one short input and output example; long examples go to references/.
• State the stop condition and what to show the user for review.
• Never put secrets, tokens or internal URLs that should not leak into the body; the agent may echo them.

6. Scripts, references and assets

The specification asks scripts to be self-contained or document their dependencies, give helpful error messages and handle edge cases. Add your own rules: pin dependency versions, avoid network access unless the skill needs it and compatibility says so, write output to stdout in a documented format, and never run commands built from untrusted text without quoting and validation.

7. Progressive disclosure and context budget

Every installed skill costs stage 1 tokens on every task, so many skills with long descriptions add up. Remove skills nobody uses, and measure the total metadata cost of the installed set. Scripts that are executed rather than read do not enter the context; only their output does, so keep that output short and structured.

8. Versioning and distribution

9. Security review

Map findings to the OWASP Top 10 for Agentic Applications 2026 where it helps: a malicious or tampered skill is a supply chain issue (ASI04, Agentic Supply Chain Vulnerabilities); a script that runs generated commands relates to ASI05 (Unexpected Code Execution); instructions that widen tool use relate to ASI02 (Tool Misuse and Exploitation). Record threats in the Agentic AI Threat Model (ai-data/agentic-threat-model).

10. Evaluation

Run activation tests several times per host, because selection is probabilistic. Record results per host and model snapshot; a model upgrade can change activation rates. Broader agent tests belong in the Agent Evaluation Plan (ai-data/agent-evaluation-plan).

11. SKILL.md skeleton

The skeleton below meets the required frontmatter fields and the recommended body sections. Delete optional fields you do not need, keep the directory name equal to name, and validate the folder with skills-ref validate before the first commit.

---
name: [skill-name]
description: [What it does in one sentence]. Use when [trigger situations and keywords].
license: [Licence name or LICENSE.txt]
compatibility: [Only if needed: required tools, packages or network access]
metadata:
  version: "[1.0.0]"
  owner: "[team]"
---

# [Skill title]

## When to use
[Scope in one paragraph. Name the near misses that should not use this skill.]

## Inputs to confirm
1. [Input one; ask the user if missing]
2. [Input two]

## Procedure
1. Run `scripts/[script].py [args]` and read its JSON output.
2. [Decision step, with the rule or a pointer to references/[FILE].md]
3. Draft the output using `assets/[template].md`.
4. Check the draft against [criteria] and show it to the user for review.

## Edge cases
- [Case]: [what to do]

## Do not
- [Action the skill must never take]

12. Glossary and references

References:

• Agent Skills, Specification (checked 2026-10-22): https://agentskills.io/specification
• Agent Skills, Overview (origin, open development): https://agentskills.io/
• skills-ref reference library: https://github.com/agentskills/agentskills/tree/main/skills-ref
• OWASP GenAI Security Project, OWASP Top 10 for Agentic Applications for 2026, December 2025: https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/
• Related templates: AGENTS.md (dev/agents-md), Context Engineering Specification (ai-data/context-engineering-spec), Agent Tool and Function Catalogue (ai-data/tool-catalogue).

Standard and licence note

Based on the open Agent Skills specification published at agentskills.io (originally developed by Anthropic and released as an open standard), checked on 2026-10-22: directory layout, frontmatter fields and their constraints, progressive disclosure stages and size guidance, file reference guidance and skills-ref validation. The specification carries no version number, so record the date you checked it and review the current text before use. OWASP Top 10 for Agentic Applications 2026 IDs and short names are cited for mapping with attribution to the OWASP GenAI Security Project (CC BY-SA 4.0). The design, review and evaluation structure and all wording here are original. Template licence: MIT.