Add Reusable Capabilities to AI Agents with skills.sh
Every time you start a new chat with an AI coding agent, you’re starting from zero. The agent doesn’t know your folder structure, your component naming conventions, or your team’s deployment rules. You paste the same context block again. You re-explain the same constraints. It’s tedious, and it doesn’t scale.
skills.sh offers a practical fix: a growing ecosystem of reusable agent capabilities you can install once and use across supported agents and projects.
Key Takeaways
- Agent skills are reusable, on-demand instruction bundles defined by a
SKILL.mdfile with YAML frontmatter and a Markdown body. - Progressive disclosure keeps context windows lean by loading only skill names and descriptions upfront, then fetching full instructions only when relevant.
- The
skillsCLI lets you install, scope, and search skills across projects without writing any custom integration code. - Skills differ from MCP servers: use skills for repeatable prompt-based workflows, and MCP for typed, API-style interactions with external systems.
- Always inspect third-party skills—especially those containing scripts—before installing, since they may execute in your local environment depending on your agent setup.
What Are AI Agent Skills?
An agent skill is a structured bundle of instructions that an AI agent can load on demand. At its core, every skill is a directory containing a SKILL.md file with YAML frontmatter and a Markdown body:
my-skill/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable helpers
├── references/ # Optional: supplementary docs
└── assets/ # Optional: templates, configsThe frontmatter requires two fields at minimum:
---
name: react-component-review
description: Reviews React components for performance issues, accessibility, and team conventions. Use when the user asks to review, audit, or check a component.
---The name must match the directory name (lowercase, hyphens only). The description is what the agent uses to decide whether to activate the skill—treat it as a routing rule, not a title.
How Progressive Disclosure Keeps Context Lean
This is the mechanism that makes skills practical at scale. Agents don’t load all skill content upfront. Instead, they follow three steps:
- Discovery — At startup, only
nameanddescriptionare loaded into the agent’s awareness. - Activation — When a user request semantically matches a skill’s description, the agent reads the full
SKILL.mdbody. - Execution — Scripts or reference files inside the skill are only fetched if the instructions call for them.
This means you can register dozens of skills without bloating the context window on every request.
Installing Skills with the Skills CLI
The skills CLI is the primary interface for managing agent skills. You don’t need to build any integration—just run:
npx skills add vercel-labs/agent-skillsCommon options you’ll actually use:
# Install globally across all projects
npx skills add -g vercel-labs/agent-skills
# Install only specific skills from a repo
npx skills add vercel-labs/agent-skills --skill frontend-design
# List what's available before installing
npx skills add vercel-labs/agent-skills --list
# Search the ecosystem
npx skills find typescriptSkills can be installed at project scope (committed with your repo, shared with your team) or globally for your own use. The CLI also supports local paths and full Git URLs.
Discover how at OpenReplay.com.
Skills vs. MCP Servers and Plugins
Skills are not the same as MCP servers or agent plugins. MCP servers expose typed tools that agents call with structured inputs and outputs—they’re appropriate when you need strict API-style control over external systems. Skills are simpler: they’re plain Markdown instructions that guide agent behavior without requiring any server infrastructure.
Use a skill when you have a repeatable workflow that’s currently living in a prompt you copy-paste. Use MCP when you need the agent to interact with an external API in a controlled, typed way.
⚠️ A Note on Security
Skills are not verified by default. The skills.sh platform runs periodic audits, but it cannot guarantee the safety of every published skill. Before installing any third-party skill—especially one that includes a scripts/ directory—read it. Depending on your agent or runtime, scripts may execute in your local environment without sandboxing.
The Emerging Agent Skills Standard
The Agent Skills format originated with Claude but is now documented independently at agentskills.io and supported across multiple platforms, including OpenAI Codex, Spring AI, and Vercel’s toolchain. It’s a converging convention, not yet a finalized standard—but the core structure (SKILL.md, YAML frontmatter, optional supporting directories) is stable enough to build on.
Conclusion
If you’re spending time re-explaining the same project context to your coding agent, skills are the right tool. They turn copy-pasted prompts into versioned, shareable assets that load only when needed, keeping your agent’s context lean and your workflow consistent. Start with npx skills init to scaffold your first skill, or browse skills.sh to find one that already covers your workflow.
FAQs
You need an agent or client that supports the Agent Skills convention. The format itself is plain Markdown with YAML frontmatter, but it only works when your tooling implements the discovery and activation pattern. Claude introduced the concept, and tools like Vercel's toolchain, Spring AI, and OpenAI Codex now support it.
A system prompt is always loaded and applies to every request, which consumes context on each turn. A skill is loaded only when its description matches the user's intent. This selective activation lets you maintain dozens of specialized behaviors without paying the token cost upfront, making skills more scalable than monolithic prompts.
Yes. The skills CLI accepts local paths and full Git URLs, so you can host skills in a private repository and install them the same way you would a public one. Project-scoped skills can also be committed directly to your codebase, which keeps them versioned alongside the project they support.
The agent decides which skill to activate based on semantic similarity to the user's request, so overlapping descriptions can cause unpredictable routing. Write descriptions as precise routing rules—mention exact triggers, file types, or user phrasing. If two skills genuinely overlap, consider merging them or scoping one more narrowly to avoid conflicts.
Understand every bug
Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.
