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

**Author:** Pauline Narvas, John Lindquist

---

> This guide is based on the [Vercel Community Session featuring John Lindquist](https://community.vercel.com/live/32450-community-session-how-to-create-and-publish-skills) 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.

* * *

## Why skills exist: the “blank slate” problem

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.

* * *

## 1) Understanding the architecture

### Skill vs. skill package

- 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.
  

### Passive vs. active context

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.”
    

### Progressive disclosure (how skills avoid context bloat)

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.
   

* * *

## 2) Anatomy of a skill (the part that must be correct)

### Required directory layout

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

`my-skill/ └── SKILL.md`

### Required YAML frontmatter

`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 + description constraints that matter

- `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**.
  

### Optional frontmatter fields (portable)

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)
  

### Skill body (Markdown instructions)

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
  

### Optional supporting directories (recommended for real skills)

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
  

* * *

## 3) Loading strategies and “when should this be a skill?”

### The description is the trigger

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.”
  

### Skills vs AGENTS.md (what to put where)

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
  

### Progressive complexity (a practical heuristic)

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
   

* * *

## 4) Using the `skills` CLI (install, manage, discover)

### Install skills

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`

### Common install options you’ll actually use

`# 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`

### Other CLI commands (the “day 2” stuff)

`# 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`

### Installation scope (project vs global)

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.

* * *

## 5) Publishing and discoverability (how “listing” actually works)

### There’s no special publish command for skills.sh

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.

### What you should include in a public skill repo

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
  

### Security reality check

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
  

* * *

## Resources

**Core ecosystem + docs**

- [https://skills.sh/](https://skills.sh/)
  

- [https://skills.sh/docs/cli](https://skills.sh/docs/cli)
  
- [https://skills.sh/docs/faq](https://skills.sh/docs/faq)
  
- [https://github.com/vercel-labs/skills](https://github.com/vercel-labs/skills)
  
- [https://vercel.com/changelog/introducing-skills-the-open-agent-skills-ecosystem](https://vercel.com/changelog/introducing-skills-the-open-agent-skills-ecosystem)
  
- [https://vercel.com/changelog/skills-v1-1-1-interactive-discovery-open-source-release-and-agent-support](https://vercel.com/changelog/skills-v1-1-1-interactive-discovery-open-source-release-and-agent-support)
  
- [https://vercel.com/blog/agent-skills-explained-an-faq](https://vercel.com/blog/agent-skills-explained-an-faq)
  
- [https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals)
  

**Agent Skills standard**

- [https://agentskills.io/specification](https://agentskills.io/specification)
  

**Workshop reference**

- [https://community.vercel.com/t/community-session-how-to-create-and-publish-skills/32450](https://community.vercel.com/t/community-session-how-to-create-and-publish-skills/32450)
  

**Example skills**

- [https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices](https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices)
  
- [https://skills.sh/vercel-labs/agent-browser/agent-browser](https://skills.sh/vercel-labs/agent-browser/agent-browser)

---

[View full KB sitemap](/kb/sitemap.md)