On 22 October 2026, the Agentic AI Foundation (AAIF), a Linux Foundation project, announced four new projects. One of them was Agent Skills, contributed by Anthropic. Agent Skills is an open format for giving AI agents new capabilities. A skill packages instructions, scripts and resources so that any compatible agent can load them on demand. AAIF now hosts it next to the Model Context Protocol (MCP) and AGENTS.md under vendor-neutral governance.

Interest is clearly high: Anthropic’s public anthropics/skills repository was top of GitHub’s daily trending list today. If you use coding agents, a skill is the easiest way to teach them how your team does things. In this tutorial you’ll build one from scratch following the official specification.

What a skill is

A skill is just a directory with a SKILL.md file in it. Optional folders hold anything else the agent might need:

release-notes/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: extra docs loaded on demand
└── assets/           # Optional: templates, data files

Skills don’t need a server or an SDK. They are plain files, which makes them easy to version, review and share in Git.

How agents load skills: progressive disclosure

The spec is designed to keep the agent’s context small:

  1. Metadata (~100 tokens): the name and description of every installed skill are loaded at startup.
  2. Instructions (under 5,000 tokens recommended): the full SKILL.md body is loaded only when the agent decides the skill is relevant.
  3. Resources (as needed): files in scripts/, references/ and assets/ are read only when required.

So the description is the most important line you’ll write. It’s how the agent decides whether to use the skill at all.

Step 1: Create the folder

We’ll build a skill that writes release notes from git history in a consistent house style.

mkdir -p release-notes/scripts release-notes/assets
cd release-notes

Step 2: Write the frontmatter

SKILL.md starts with YAML frontmatter. Only two fields are required:

---
name: release-notes
description: Drafts release notes from git commits between two tags, grouped into Features, Fixes and Breaking Changes in our house style. Use when the user asks for release notes, a changelog entry, or "what changed" between versions.
license: MIT
metadata:
  author: crazy-learners
  version: "1.0"
---

The spec’s rules for name:

  • 1 to 64 characters
  • lowercase letters, numbers and hyphens only
  • must not start or end with a hyphen, and must not contain --
  • must match the folder name (release-notes here)

And for description: 1 to 1,024 characters, saying both what the skill does and when to use it, with keywords a user might actually type. “Helps with releases” is too vague. The example above names the trigger phrases.

Optional fields include license, compatibility (environment needs, max 500 characters), metadata (string key-value pairs) and the experimental allowed-tools.

Step 3: Write the instructions

After the frontmatter comes ordinary Markdown. There are no format rules, but the spec recommends step-by-step instructions, input/output examples and common edge cases:

# Release notes

## Steps
1. Ask for the two git tags if the user did not give them.
2. Run `scripts/commits.sh <from-tag> <to-tag>` to list commits.
3. Group commits by prefix:
   - `feat:` -> Features
   - `fix:` -> Fixes
   - any commit containing `BREAKING CHANGE` -> Breaking Changes (list first)
4. Rewrite each item as one plain-English sentence for end users.
5. Fill in `assets/template.md` and return the result.

## Rules
- Never invent changes that are not in the commit list.
- Skip `chore:`, `ci:` and `test:` commits.
- Mention PR numbers in brackets when present, e.g. (#123).

## Example
Input commit: `feat(auth): add passkey login (#481)`
Output line: `- You can now sign in with a passkey. (#481)`

Keep SKILL.md under about 500 lines. Move longer reference material into references/ and link to it with a relative path. The spec advises keeping file references only one level deep.

Step 4: Add a script and a template

Scripts let the agent do things reliably instead of improvising shell commands. Make them self-contained, with clear error messages:

#!/usr/bin/env bash
# scripts/commits.sh - list commit subjects between two tags
set -euo pipefail

if [ "$#" -ne 2 ]; then
  echo "Usage: commits.sh <from-tag> <to-tag>" >&2
  exit 1
fi

git rev-parse "$1" >/dev/null 2>&1 || { echo "Unknown tag: $1" >&2; exit 1; }
git rev-parse "$2" >/dev/null 2>&1 || { echo "Unknown tag: $2" >&2; exit 1; }

git log --pretty=format:'%s' "$1..$2"

chmod +x scripts/commits.sh

And a simple template in assets/template.md:

## {{version}} ({{date}})

### Breaking Changes
{{breaking}}

### Features
{{features}}

### Fixes
{{fixes}}

Step 5: Validate the skill

The spec points to the skills-ref reference library for validation. It checks that your frontmatter is valid and follows the naming rules:

skills-ref validate ./release-notes

Install instructions are in the agentskills/agentskills repository. Run validation in CI so a broken skill never gets merged.

Step 6: Install and test it

Where skills live depends on your agent. Most agents that support the format read skills from a project or user skills directory, so check your tool’s docs for the exact path. Then test with prompts that should and shouldn’t trigger the skill:

  • “Write release notes from v1.4.0 to v1.5.0” should activate the skill.
  • “Fix this failing test” should not.

If the skill triggers too often or too rarely, adjust the description. That is almost always the fix.

Best practices

  • One skill, one job. Small focused skills are chosen more accurately than big catch-all ones.
  • Treat skills like code. Review them in pull requests, because scripts in a skill run on developer machines.
  • Only install skills you trust. A skill can include executable scripts, so read third-party skills before you use them, just as you would a new dependency.
  • Use allowed-tools carefully. It is experimental, and support varies between agents.

Takeaway

With Agent Skills now governed by the Linux Foundation’s AAIF, a skill you write today isn’t tied to one vendor. All you need is a folder, a SKILL.md with a sharp description, and optional scripts and references. Start by turning one repetitive task your team does, such as release notes, code-review checklists or deployment steps, into a skill.

Sources: Linux Foundation: AAIF announces Agent Skills, Open Responses, OpenEnv and OpenSandbox · Agent Skills Specification · agentskills/agentskills on GitHub