VercelVercel

Agent Skills: Creating, Installing, and Sharing Reusable Agent Context

This guide will cover what skills are, how to create custom skills for yourself and your team, and how to publish them to the community.

Knowledge Base/AI
4 min read
Last updated February 13, 2026

This guide is based on the Vercel Community Session featuring John Lindquist and updated to match the current Agent Skills standard, the skills CLI, and how skills.sh actually works.

AI skills turn “one-off prompts” into a reusable, versionable library of agent behavior. The goal is simple: stop re-explaining your project’s tribal knowledge every time you open a new chat.

Models know general programming languages and frameworks, but they don’t know:

  • Your folder structure
  • Your design system
  • Your deployment rules
  • What “good” means in your org

Skills are the “npm moment” for context: instead of copy/pasting long instructions into every session, you install a skill once and let the agent load it when relevant.

  • A skill is a single folder containing a SKILL.md (plus optional supporting files).
  • A skill package is a repo (or directory) that contains one or more skills.

You should split context into two buckets:

  • Passive context (always available): Use an AGENTS.md (or your agent’s equivalent) for rules that apply all the time.
    • Examples: security guardrails, formatting rules, “always use strict TS,” “never bypass auth,” etc.
  • Active context (on-demand): Use skills for specialized workflows the agent should load only when needed.
    • Examples: “deploy to Vercel,” “analyze CSV,” “write a PRD,” “review React code for performance.”

Skills are designed so agents don’t load everything up-front:

  1. Metadata (name + description) is available early so the agent can decide whether it’s relevant.
  2. Full instructions (the body of SKILL.md) load only when the agent activates the skill.
  3. Resources (scripts/references/assets) load only if the skill tells the agent to use them.

A skill is a directory containing at minimum a SKILL.md file:

my-skill/
└── SKILL.md

SKILL.md must start with YAML frontmatter and include:

  • name (required)
  • description (required)

Minimal example:

---
name: my-skill
description: Do X for Y projects. Use when the user asks about X or mentions Y.
---


# Instructions


(Your steps, constraints, and examples go here.)
  • name must match the parent directory name.
  • name is lowercase letters/numbers/hyphens only (no uppercase).
  • description should say what the skill does and when to use it.

These are part of the spec and safe to use across ecosystems:

  • license
  • compatibility (only when environment requirements exist)
  • metadata (arbitrary key/value data; a good place for your semver)
  • allowed-tools (experimental; support varies by agent)

The Markdown body has no required format, but if you want reliability, use a predictable structure:

  • What this skill does
  • When to use it (and when not to)
  • Inputs needed
  • Step-by-step procedure
  • Validation / “how to know we’re done”
  • Common failure modes and fixes

Use these to keep SKILL.md concise and load details only when needed:

  • scripts/ — executable helpers
  • references/ — longer docs, checklists, templates
  • assets/ — static templates, sample configs, diagrams

Most systems decide whether to activate a skill primarily from its description. So don’t treat description like a title—treat it like a routing rule.

Bad:

  • “Helps with PDFs.”

Good:

  • “Extract text and tables from PDFs, fill forms, merge documents. Use when the user mentions PDFs, forms, scanning, or document extraction.”

Be blunt about it:

Put it in AGENTS.md when:

  • It applies to almost every task
  • You want maximum reliability (no activation decision)
  • The agent should never ignore it

Put it in a skill when:

  • It’s a specialized workflow
  • It’s used occasionally
  • You want it discoverable/reusable across repos/teams

Start simple and only add complexity when you hit a real wall:

  1. Markdown-only skill (most skills)
  2. Add scripts/ when you need deterministic automation
  3. Use a tool/MCP integration only when you need strict typed payloads or strong control over external calls

Install a package (repo) like this:

npx skills add <owner/repo>

The CLI supports multiple sources, including direct skill paths and local folders:

# GitHub shorthand
npx skills add vercel-labs/agent-skills


# Full GitHub URL
npx skills add https://github.com/vercel-labs/agent-skills


# Direct path to a specific skill inside a repo
npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines


# GitLab URL
npx skills add https://gitlab.com/org/repo


# Any git URL
npx skills add git@github.com:vercel-labs/agent-skills.git


# Local path
npx skills add ./my-local-skills


# Install globally (available across all projects)
npx skills add -g vercel-labs/agent-skills


# List skills in a repo without installing
npx skills add vercel-labs/agent-skills --list


# Install only specific skills by name
npx skills add vercel-labs/agent-skills --skill frontend-design --skill skill-creator


# Skip prompts (CI-friendly)
npx skills add vercel-labs/agent-skills --skill frontend-design -g -y


# Install everything from a repo
npx skills add vercel-labs/agent-skills --all


# List installed skills
npx skills list


# Search skills (interactive or keyword)
npx skills find
npx skills find typescript


# Remove skills
npx skills remove
npx skills remove web-design-guidelines


# Check/update skills
npx skills check
npx skills update


# Scaffold a new skill template
npx skills init
npx skills init my-skill

The CLI can install:

  • Project scope (committed with your repo, shared with your team)
  • Global scope (available across projects for your user)

It can also install by symlink (recommended) or copy, depending on your environment.

To “publish” a skill:

  1. Put it in a git repo.
  2. Share the repo.
  3. When people install it via npx skills add, it can show up on skills.sh automatically via install telemetry.

That’s it. No registry submission flow.

At minimum:

  • Your skill folder(s) with SKILL.md

Strongly recommended:

  • A README.md explaining what the skills do and how to install them
  • Clear license and ownership info
  • Safety notes if scripts exist

Treat skills like code:

  • Read them before installing
  • Be especially careful with scripts/ (they can run commands)
  • Pin to known repos and review diffs on updates

Core ecosystem + docs

Agent Skills standard

Workshop reference

Example skills

Was this helpful?

supported.

Read related documentation

No related documentation available.

Explore more guides

No related guides available.