creating-agent-skills

name	creating-agent-skills
description	Authors, audits, and refines Agent Skills — SKILL.md files, frontmatter, progressive disclosure, and bundled scripts, references, and assets. Use when creating a new skill, improving or auditing an existing one, fixing skill frontmatter, deciding how to structure a skill's files, or checking a skill against the Agent Skills specification. Applies even when the user says only "make a skill", "write a SKILL.md", or names a skills directory without mentioning the spec.
metadata	{"version":"2.0","standard":"agent-skills"}

Creating Agent Skills

Agent Skills is an open, vendor-neutral format — a folder with a SKILL.md that teaches an agent a capability. Claude Code, Cursor, Copilot, VS Code, Codex, Gemini CLI, OpenCode, Goose and others all load the same folder.

How this skill works

These four principles apply to every workflow below. They are inline because they must not be skipped.

1. The spec is the floor

name and description are required. description is capped at 1024 characters — a hard validity limit, not a display truncation. name must be lowercase alphanumeric with single hyphens, and must match its parent directory.

Everything else — license, compatibility, metadata, allowed-tools — is optional. Full rules: references/agent-skills-spec.md.

2. Portable by default

Any frontmatter field outside those six is non-spec, and support for it is . Some are widely supported, some have an equivalent in a per-client sidecar file, and some exist in one client only — where the behaviour silently disappears rather than degrading. Check the field before assuming either way.