Agent Skills are folders that package reusable instructions, scripts, and supporting files for AI agents. Every skill has a SKILL.md file with YAML frontmatter and Markdown instructions. A compatible agent first sees only the skill's name and description, then loads the full instructions and supporting resources when the task calls for them.

That staged loading is the important part. A skill is not merely a long prompt saved to disk. It is a small, inspectable capability package designed to put the right procedure into context without loading every detail on every request.

This guide covers the open Agent Skills format. Individual products decide where skills are installed, how users invoke them, which tools they may run, and what permission prompts appear. Check your client's current documentation before relying on product-specific behavior.

What an Agent Skill is

A useful skill captures procedural knowledge that should survive beyond one chat:

  • how to review a database migration safely;
  • how to prepare a release using a team's actual checks;
  • how to turn an incident log into a timeline;
  • how to validate a content record against a local schema;
  • how to generate a report using an approved template.

The skill gives the agent a repeatable workflow, decision rules, known failure modes, and optional deterministic helpers. It does not add intelligence to the model, grant permissions by itself, or guarantee that every client will execute its instructions identically.

The specification defines a skill as a directory containing at least SKILL.md. A typical package looks like this:

release-check/
├── SKILL.md
├── scripts/
│   ├── collect-changes.mjs
│   └── validate-release.mjs
├── references/
│   ├── release-policy.md
│   └── rollback-checklist.md
└── assets/
    └── release-notes-template.md

Only SKILL.md is required. The directory names for supporting files are conventions recognized by the specification and its guidance, but the instructions still need to tell the agent what each file is for and when to use it.

SKILL.md and its frontmatter

SKILL.md starts with YAML frontmatter, followed by Markdown instructions:

---
name: release-check
description: Prepare and validate a software release. Use when a user asks for release readiness, release notes, version checks, or a pre-deployment checklist.
license: MIT
compatibility: Requires Node.js 20 and read access to a Git repository.
metadata:
  author: example-team
  version: "1.2.0"
---

# Release check

Inspect the repository before proposing a release.

## Workflow

1. Read package metadata and release documentation.
2. Run `node scripts/collect-changes.mjs`.
3. Classify blockers as correctness, security, migration, or operations.
4. Draft notes using `assets/release-notes-template.md`.
5. Run `node scripts/validate-release.mjs`.

The required frontmatter fields are:

  • name: 1–64 characters using lowercase letters, numbers, and hyphens. It cannot start or end with a hyphen. The specification also requires it to match the parent directory name.
  • description: a non-empty description, up to 1,024 characters, that says both what the skill does and when it should be used.

Optional standard fields include license, compatibility, string-to-string metadata, and the experimental allowed-tools field. Treat allowed-tools as experimental rather than a portable security boundary. A client may not implement it, and tool authorization remains a client responsibility.

Write the description as a routing rule

The description is not marketing copy. Compatible clients commonly expose skill metadata during discovery, so vague descriptions make activation unreliable.

Weak:

description: Helps with releases.

Useful:

description: Prepare and validate a software release. Use for release readiness, changelog drafting, version checks, or rollback-plan review. Do not deploy.

The second version names the jobs, includes likely user language, and sets a high-risk boundary. It still cannot force every client to activate the skill, but it gives the model a better selection signal.

Progressive disclosure: why the folder matters

Agent Skills use progressive disclosure in three levels:

  1. Metadata at discovery: the client can expose the name and description without loading the full procedure.
  2. Instructions at activation: the full SKILL.md body enters context when the skill is relevant.
  3. Resources on demand: scripts, references, and assets are read or run only when needed.

The official guidance recommends keeping SKILL.md below 500 lines and roughly 5,000 tokens. That is a design target, not permission to fill every skill to the limit.

Progressive disclosure solves two practical problems. First, ten installed skills should not require ten full manuals in every model call. Second, detailed material can stay close to the workflow without distracting the agent before it becomes relevant.

It only works if the instructions contain loading conditions. This is weak:

See the references folder for more information.

This is actionable:

Read `references/release-policy.md` before changing a version.
Read `references/rollback-checklist.md` only if the release changes persistent data or infrastructure.

The condition tells the agent when the extra context earns its cost.

Scripts, references, and assets

Scripts turn exact checks into code

Use scripts/ for deterministic operations: schema validation, file conversion, checksums, parsing, or report generation. Do not ask a language model to imitate a validator when a short program can return an exact result.

A validation script should:

  • accept explicit inputs;
  • avoid hidden network calls;
  • produce concise stdout and useful non-zero exit codes;
  • be safe to run twice where possible;
  • refuse destructive actions unless the workflow includes explicit approval;
  • avoid printing secrets or entire sensitive files.

Scripts increase the trust surface. Reading Markdown cannot directly alter a machine; executing a bundled program can. Review the source, pin or avoid dependencies, and use a sandbox or restricted environment when the origin is not fully trusted.

References hold conditional detail

Use references/ for policies, schemas, API notes, error catalogs, and long examples. A reference should have a clear trigger in SKILL.md. If the agent needs a rule on every run, keep the short rule in the main file and move only the detail out.

Do not copy large vendor documentation sets into a skill. They go stale, consume review time, and can conflict with current APIs. Prefer a small compatibility note plus links to authoritative sources when network access is acceptable.

Assets are inputs, not instructions

Use assets/ for templates, sample data, images, and files copied into outputs. A release-note template belongs in assets; the rules for deciding what enters release notes belong in SKILL.md.

Treat every asset as untrusted data until its format and origin are known. Spreadsheet formulas, office macros, HTML templates, and archives can carry risks beyond plain text.

When a skill is the right tool

Create a skill when all of these are true:

  • the workflow recurs;
  • there is a recognizable trigger;
  • local or team-specific procedure materially improves the result;
  • the procedure can be reviewed as files;
  • failures can be tested or checked.

A skill is especially useful when the agent knows the general domain but not your operating policy. Models understand software releases; they do not know that your team blocks releases without a rollback owner and a verified migration backup.

When not to create one

Do not create a skill for a one-off request, a two-sentence preference, or a workflow that needs a callable external service more than instructions. A project rule may suit always-on conventions. An MCP server may suit live data and actions. A normal prompt is enough for a temporary task.

Avoid a single "do everything" skill. If its description matches every request, it pollutes discovery and hides unrelated procedures inside one large file.

For the underlying prompting principles, read prompt engineering for code. Skills package durable workflow context; they do not replace clear instructions.

Build a realistic skill from zero

Suppose a small SaaS team repeatedly asks an agent to prepare releases. The agent often drafts good notes but misses migration risk and occasionally interprets "ship it" as permission to deploy. The skill should make preparation reliable while keeping deployment outside scope.

Step 1: define the contract

Write a one-sentence job:

> Inspect a repository and produce a release-readiness report plus draft notes; never deploy or modify production.

List inputs and outputs:

  • inputs: repository path, target version, optional issue list;
  • outputs: blocker list, checks run, draft release notes, rollback questions;
  • prohibited actions: publishing, tagging, deployment, secret access.

If you cannot state this contract, the skill is too broad.

Step 2: create the smallest valid folder

release-check/
└── SKILL.md

Add valid frontmatter and a workflow with inspection, classification, validation, and handoff. Test that first. Add support files only after a real failure shows they are needed.

Step 3: move deterministic work into scripts

After several runs, you notice the agent misreads version consistency across package.json, a CLI banner, and a deployment manifest. Add scripts/check-versions.mjs that reads known files and returns a small JSON result:

{
  "ok": false,
  "expected": "2.4.0",
  "mismatches": [
    { "file": "src/version.ts", "found": "2.3.1" }
  ]
}

The script reports; it does not silently edit. The agent can explain the mismatch and ask before making changes.

Step 4: add references after observed misses

If migration reviews repeatedly omit the backup rule, add references/migration-policy.md and a precise instruction:

If the diff changes schemas, migrations, or persistent-data code, read
`references/migration-policy.md` before assigning release status.

This is evidence-driven skill design: observed failure, focused rule, focused test.

Step 5: add a validation loop

End the workflow with:

  1. Generate the report.
  2. Run the validator against its structured summary.
  3. Fix missing fields.
  4. Run it again.
  5. Return the report with the checks actually run and any uncertainty.

Validation should not claim semantic truth it cannot prove. A script can confirm that a rollback owner field exists; it cannot prove that the owner is available at 2 a.m.

Test the skill, not just the YAML

The official skills-ref tool can validate frontmatter and naming:

skills-ref validate ./release-check

That catches format errors, not workflow quality. Build a small test set with four groups:

  • should trigger: "Prepare release readiness for version 2.4.0."
  • should not trigger: "Explain semantic versioning."
  • normal path: clean version files, no migration, tests pass.
  • failure paths: missing tool, malformed manifest, migration without rollback information, validator error.

Record expected properties instead of one exact paragraph. For example:

{
  "mustMention": ["deployment not performed", "rollback"],
  "mustRun": ["check-versions"],
  "mustNotRun": ["deploy", "publish"],
  "status": "blocked"
}

Run the cases with the clients and model versions you actually support. Agent behavior can vary even when the package format is valid.

Versioning and maintenance

The Agent Skills frontmatter does not define a required universal version field. A common, portable place for your own version string is metadata, while Git tags or package releases can track the distributable artifact.

Use a practical policy:

  • patch for wording, examples, or checks that preserve the workflow contract;
  • minor for backward-compatible capabilities or new optional resources;
  • major when triggers, required inputs, outputs, permissions, or side effects change.

Keep a changelog when other people depend on the skill. Pin a reviewed commit or release in managed environments. Re-run validation and behavioral cases after changing the skill, client, model, scripts, or external API.

Do not assume that a valid old skill stays safe forever. Dependencies age, commands disappear, URLs change, and a once-read-only API can gain write operations.

Security review before installation

Skills can influence agent decisions and may cause tools or scripts to run. Treat installation like a code review, not like importing a harmless text snippet.

Check:

  • Origin: Who published it, and is the source repository the expected one?
  • Instructions: Does it request secrets, broad file access, disabled safeguards, or hidden data transfer?
  • Scripts: What processes, network calls, child commands, and file writes occur?
  • References and assets: Can they contain prompt injection, macros, executable content, or private data?
  • Tool scope: Are write, shell, browser, and network tools truly needed?
  • Failure mode: Can the skill stop safely when validation, authorization, or a dependency fails?
  • Update path: Are updates reviewed, pinned, and reversible?

Never place credentials in SKILL.md, scripts, sample commands, or assets. Read secrets from a client-managed secret store or environment only when the user has authorized the operation. Redact outputs, and do not send repository contents to a remote service just because a script can.

For high-impact actions, separate preparation from execution. A deployment skill can produce a plan and commands, but execution should require explicit approval at the moment of action.

Common failures and fixes

The skill never activates

The description may name a domain without naming the task. Add concrete trigger language users actually say. Validate the package and confirm that your client supports skills at the configured location.

The skill activates too often

The description is too broad or overlaps another skill. Narrow the job and add exclusions. Split unrelated workflows.

The agent ignores a reference

The main file probably says "see references" without a condition. Name the exact file and trigger. Keep safety-critical short rules in SKILL.md.

The script works only on the author's machine

Document runtime requirements in compatibility, use relative paths from the skill root, avoid ambient dependencies, and test on every supported operating system.

The skill consumes too much context

Move large schemas and examples into references. Replace repeated prose with a short decision table. Keep tool output concise and retrieve only the slices needed.

Validation passes but results are poor

Structural validation proves conformance, not usefulness. Add behavioral cases from real failures and compare the skill against a no-skill baseline.

FAQ

Are Agent Skills the same as prompts?

No. A prompt is instruction content sent to a model. A skill is a file-based package with discovery metadata, instructions, and optional resources designed for on-demand loading. Its main body still contains prompt-like instructions.

Does SKILL.md run automatically?

The open format does not define one universal activation or execution interface. A compatible client decides how it discovers, activates, reads, and runs skill content.

Can a skill call an API?

Its instructions can direct an agent to use available tools, and bundled scripts may call APIs if the client permits execution and network access. That access is not granted by the skill format.

How many skills should I install?

There is no useful universal number. Metadata still consumes attention, and overlapping descriptions hurt selection. Keep the set relevant to current work and remove skills that never trigger.

Should scripts be mandatory?

No. Use them where deterministic behavior beats generated reasoning. A policy or editorial workflow may need only instructions and references.

Can one skill work across every agent client?

The file format can be portable while runtime behavior is not. Tool names, sandboxing, installation paths, activation controls, and supported optional fields vary by client. Test each target client.

A shipping checklist

  • [ ] Folder name and name match.
  • [ ] Description states what and when.
  • [ ] Main instructions are focused and below the recommended size.
  • [ ] Every support file has a loading condition.
  • [ ] Scripts have explicit inputs, safe outputs, and failure codes.
  • [ ] Format validation passes.
  • [ ] Trigger, non-trigger, success, and failure cases pass.
  • [ ] No credentials or private data are bundled.
  • [ ] Side effects require the right authorization.
  • [ ] Version and rollback path are documented.

Continue learning

Sources

These are specification and vendor-primary sources. The open specification defines package conformance; activation, installation, permission prompts, and script execution remain client-specific.

ai-agentsagent-skillsskill-mdcontext-engineeringdeveloper-tools