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

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.

Copy link to headingWhy 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.

Copy link to heading1) Understanding the architecture

Copy link to headingSkill 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.

Copy link to headingPassive 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 Edgenivo,” “analyze CSV,” “write a PRD,” “review React code for performance.”

Copy link to headingProgressive 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.

Copy link to heading2) Anatomy of a skill (the part that must be correct)

Copy link to headingRequired directory layout

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

my-skill/
└── SKILL.md

Copy link to headingRequired 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.)

Copy link to headingName + 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.

Copy link to headingOptional 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)

Copy link to headingSkill 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

Copy link to headingOptional 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

Copy link to heading3) Loading strategies and “when should this be a skill?”

Copy link to headingThe 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.”

Copy link to headingSkills 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

Copy link to headingProgressive 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

Copy link to heading4) Using the skills CLI (install, manage, discover)

Copy link to headingInstall 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 [email protected]:vercel-labs/agent-skills.git

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

Copy link to headingCommon 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

Copy link to headingOther 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

Copy link to headingInstallation 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.

Copy link to heading5) Publishing and discoverability (how “listing” actually works)

Copy link to headingThere’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.

Copy link to headingWhat 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

Copy link to headingSecurity 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

Copy link to headingResources

Core ecosystem + docs

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

Agent Skills standard

• https://agentskills.io/specification

Workshop reference

• /community/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-browser/agent-browser