AgentPMT/how-to-use-vercel-skills

How to Use Vercel Skills

Agent skills are folders of instructions, scripts, and resources that AI agents can discover and use. The format is an open standard supported by 40+ agents including Claude Code, Cursor, GitHub Copilot, Windsurf, Cline, Gemini CLI, OpenAI Codex, Roo Code, and many others.

When to Use This Skill

• Creating a new agent skill from scratch
• Structuring a SKILL.md file with correct frontmatter and body
• Adding install commands to a website, README, or documentation
• Publishing skills so they appear on skills.sh
• Understanding how the skills CLI works (install, find, list, update, remove)
• Organizing a repository that contains multiple skills

Skill File Structure

A skill is a directory containing at minimum a SKILL.md file. The directory name must exactly match the name field in the frontmatter.

Minimal structure

my-skill/
  SKILL.md

Full structure with optional directories

my-skill/
  SKILL.md              # Required -- agent instructions
  scripts/              # Optional -- executable helpers (bash, python, js)
  references/           # Optional -- detailed docs loaded on demand
  assets/               # Optional -- templates, schemas, static files

SKILL.md Format

Every SKILL.md must start with YAML frontmatter followed by markdown content.

Frontmatter

---
name: my-skill-name
description: What this skill does and when to use it. Include keywords that help agents match tasks to this skill.
---

Required fields

| Field | Rules | |-------|-------| | name | 1-64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen. No consecutive hyphens (--). Must match the parent directory name. | | description | 1-1024 characters. Describe what the skill does AND when to use it. Include specific keywords that help agents identify relevant tasks. |

Optional fields

| Field | Purpose | |-------|---------| | license | License name or reference to a bundled LICENSE file. | | compatibility | Max 500 characters. Environment requirements (e.g., "Requires git, docker, jq"). Most skills do not need this. | | metadata | Arbitrary key-value pairs. Common keys: author, version. | | allowed-tools | Space-delimited list of pre-approved tools. Experimental, support varies by agent. |

Full frontmatter example

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
license: MIT
compatibility: Requires Python 3.10+
metadata:
  author: example-org
  version: "2.1"
allowed-tools: Bash(python:*) Read
---

Name field rules

Valid:

• pdf-processing
• data-analysis
• code-review
• my-skill-v2

Invalid:

• PDF-Processing (uppercase not allowed)
• -pdf (cannot start with hyphen)
• pdf- (cannot end with hyphen)
• pdf--processing (consecutive hyphens not allowed)
• my skill (spaces not allowed)

Writing a good description

The description is a routing rule, not a title. Agents see only the name and description at startup to decide whether to load the full skill.

Bad:

description: Helps with PDFs.

Good:

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

Body content

The markdown body after frontmatter contains the actual instructions. There are no format restrictions, but recommended sections include:

• What this skill does
• When to use it (and when not to)
• Step-by-step procedure
• Examples of inputs and outputs
• Common edge cases and failure modes
• Validation criteria ("how to know it worked")

Keep the main SKILL.md under 500 lines. Move detailed reference material to files in references/.

Progressive Disclosure

Skills load in stages to minimize context usage:

1. Metadata (~100 tokens): name and description are loaded at startup for all installed skills.
2. Instructions (< 5000 tokens recommended): The full SKILL.md body is loaded when the agent activates the skill.
3. Resources (as needed): Files in scripts/, references/, and assets/ are loaded only when required.

Install Commands for Websites and READMEs

Install all skills from a repo

npx skills add owner/repo

Install a specific skill from a multi-skill repo

npx skills add owner/repo --skill skill-name

Install all skills from a repo non-interactively

npx skills add owner/repo --all -y

Install to a specific agent only

npx skills add owner/repo --agent claude-code
npx skills add owner/repo --agent cursor

Install globally (user-wide, not just current project)

npx skills add owner/repo --global

Example website/README copy

For a repo at github.com/myorg/my-agent-skills with a skill called my-workflow:

## Install

Install all skills:

npx skills add myorg/my-agent-skills

Install just the workflow skill:

npx skills add myorg/my-agent-skills --skill my-workflow

CLI Reference

| Command | Purpose | |---------|---------| | npx skills add <source> | Install skills from a GitHub repo, URL, or local path | | npx skills list | Show installed skills (alias: ls) | | npx skills find [query] | Search for skills interactively or by keyword | | npx skills check | Check for available updates | | npx skills update | Upgrade all installed skills | | npx skills init [name] | Generate a new SKILL.md template | | npx skills remove [skills] | Uninstall skills |

Source formats the CLI accepts

• GitHub shorthand: owner/repo
• Full GitHub URL: https://github.com/owner/repo
• Direct skill path: https://github.com/owner/repo/tree/main/skills/skill-name
• GitLab and other git hosts
• Local filesystem paths

Key flags

| Flag | Purpose | |------|---------| | -s, --skill | Install a specific skill by name, or '*' for all | | -a, --agent | Target a specific agent (e.g., claude-code, cursor) | | -g, --global | Install to user home directory instead of project | | --copy | Copy files instead of creating symlinks | | -y, --yes | Skip confirmation prompts | | --all | Install all skills to all agents non-interactively | | -l, --list | Preview available skills without installing |

Where Skills Get Installed

The CLI automatically places skills in the correct location for each agent:

| Agent | Project path | Global path | |-------|-------------|-------------| | Claude Code | .claude/skills/ | ~/.claude/skills/ | | Cursor | .agents/skills/ | ~/.cursor/skills/ | | GitHub Copilot | .agents/skills/ | varies | | Windsurf | .agents/skills/ | varies |

40+ agents are supported. The CLI handles path resolution automatically.

Repository Organization

Single skill repo

my-repo/
  SKILL.md

Multi-skill repo (recommended for collections)

my-repo/
  skills/
    skill-one/
      SKILL.md
    skill-two/
      SKILL.md
      scripts/
        helper.sh
      references/
        detailed-guide.md

The CLI searches these locations automatically:

• Repository root
• skills/ directory and its subdirectories
• skills/.curated/, skills/.experimental/, skills/.system/
• Agent-specific directories (.claude/skills/, .agents/skills/, etc.)
• Recursive fallback if nothing found in standard locations

Skills can be nested in subdirectories (e.g., skills/category/my-skill/SKILL.md) and the CLI will still discover them.

Publishing and Discovery

Skills appear on skills.sh automatically when people install them via the CLI. There is no separate publish step. To get your skill listed:

1. Put your skill in a public GitHub repo with a valid SKILL.md
2. Share the install command: npx skills add owner/repo
3. As people install it, it appears and climbs the skills.sh leaderboard

Validation

Use the reference library to validate your skill before publishing:

npx skills-ref validate ./my-skill

This checks that frontmatter is valid and naming conventions are followed.

Quick Checklist for a New Skill

1. Create a directory with a lowercase, hyphenated name
2. Add a SKILL.md with name and description in the frontmatter
3. Ensure name exactly matches the directory name
4. Write a description that works as a routing rule (what it does + when to use it)
5. Write clear instructions in the markdown body
6. Keep SKILL.md under 500 lines; use references/ for detailed docs
7. Add scripts/ for any executable helpers
8. Test by running npx skills add . locally
9. Push to a public GitHub repo
10. Share the install command: npx skills add owner/repo