agentskills-io

Agent Skills (agentskills.io)

Create portable skills for AI agents. Works with Claude Code, Cursor, GitHub Copilot, OpenAI integrations, VS Code (symlinks enable sharing across tools).

Resources

Specification: https://agentskills.io/specification | Validator: https://github.com/agentskills/agentskills

Structure

skill-name/ ├── SKILL.md # Required (frontmatter + instructions, <5000 tokens activation) ├── scripts/ # Optional: executable code ├── references/ # Optional: detailed docs └── assets/ # Optional: templates, static files Rules: Dir name = frontmatter name:. Only 3 subdirs. SKILL.md <500 lines. ~100 tokens for discovery (name+desc).

Required

name: 1-64 chars, lowercase alphanumeric-hyphens (^[a-z0-9]+(-[a-z0-9]+)*$) description: 1-1024 chars, include "Use when..." (discovery budget: ~100 tokens)

Optional

license: SPDX identifier (Apache-2.0, MIT) | compatibility: Environment reqs (<500 chars) metadata: Key-value pairs (author, version, tags) | allowed-tools: Space-delimited tool list

Validation

# Install permanently (vs ephemeral uvx) uv tool install git+https://github.com/agentskills/agentskills#subdirectory=skills-ref # Or use uvx for one-shot validation uvx --from git+https://github.com/agentskills/agentskills#subdirectory=skills-ref skills-ref validate ./skill CommandDescriptionskills-ref validate <path>Check structure, frontmatter, token budgetsskills-ref read-properties <path>Extract metadataskills-ref to-prompt <path>Generate prompt format

Writing Rules

Imperative language: "Check: command" not "You might want to..." Concrete examples with expected output; handle common errors with solutions Progressive disclosure: core in SKILL.md (<5000 tokens), details in references/

Common Errors

ErrorFixInvalid nameLowercase alphanumeric-hyphens onlyMissing descriptionAdd description: field with "Use when..."Description too long<1024 chars, move details to bodyInvalid YAMLCheck indentation, quote special charsMissing SKILL.mdFilename must be exactly SKILL.mdDir name mismatchDirectory name must match name: field

Quick Workflow

Create: mkdir skill-name && touch skill-name/SKILL.md Add frontmatter (name, description with "Use when...") Write instructions (bullets, not prose); validate: skills-ref validate ./skill-name Test with AI agent, iterate; add LICENSE, push to repository

Plugin Structure (Claude Code)

plugin-name/ ├── .claude-plugin/plugin.json ├── README.md, LICENSE, CHANGELOG.md # CHANGELOG.md tracks versions ├── skills/skill-name/SKILL.md ├── agents/ # Optional: subagents (.md files) └── examples/ # Optional: full demo projects Distinctions: Plugin examples/ = runnable projects. Skill assets/ = static resources only.

Batch Validation & Versioning

bash scripts/validate-skills-repo.sh # Validate all skills in repo bash scripts/bump-changed-plugins.sh # Auto-bump only changed plugins (semver)

Minimal Example

• ---
• name: example-skill
• description: Brief description. Use when doing X.
• ---
• # Example Skill
• ## Prerequisites
• Required tools
• ## Instructions
• 1. First step: `command`
• 2. Second step with example
• ## Troubleshooting
• **Error**: Message → **Fix**: Solution

Symlink Sharing

Share skills across Claude Code, Cursor, VS Code: ln -s /path/to/skills ~/.cursor/skills

References

specification.md - Full YAML schema, token budgets examples.md - Complete examples across platforms validation.md - Error troubleshooting best-practices.md - Advanced patterns, symlink setup