Writing a Vercel Skill doesn’t require a Computer Science degree or a massive enterprise framework. If you know how to write a Markdown file, you know how to build a skill.
The beauty of the Open Agent Skills ecosystem is that it relies on plain text and standard protocols. Here is the no-nonsense guide to building your first skill and getting it into the hands of your team.
Step 1: Initialize the Skill
Vercel provides a CLI to handle the boilerplate. Open your terminal and run:
npx skills init my-database-skillThis creates a new directory with a single file: SKILL.md. That’s it. There is no package.json, no node_modules, and no complex build steps.
The Scenario: You’re the lead engineer at a startup. Every time you hire someone new, they accidentally write N+1 queries using Prisma because they don’t know the company’s specific data-loading patterns. You could yell at them in pull requests, or you could take two minutes to
inita skill that teaches the AI how to write the queries correctly the first time.
Step 2: Write the SKILL.md File
Open the SKILL.md file. You need two things: YAML frontmatter (for metadata) and Markdown content (for instructions).
The Frontmatter
The frontmatter tells the CLI and the agent what this skill is.
---
name: prisma-optimization-guide
description: Company standards for writing efficient Prisma queries and avoiding N+1 problems.
---The Instructions
This is where you talk to the agent. Be direct. Don’t say “Please try to use…” Say “You must use…”
# Prisma Optimization Standards
## When to Use This Skill
- When the user asks you to write database queries.
- When reviewing files in the `/app/api` directory.
## Core Rules
1. **Never use lazy loading in loops.** If you are fetching a list of users and their posts, use `include`.
2. **Select only what you need.** Do not use `select: { * }` or omit the `select` block if you only need the ID.
3. **Use transactions for multi-step writes.** If a user creates an account and a profile, wrap them in `$transaction`.
## Code Example
**BAD:**
```typescript
const users = await prisma.user.findMany();
for (const user of users) {
const posts = await prisma.post.findMany({ where: { userId: user.id } }); // N+1!
}GOOD:
const users = await prisma.user.findMany({
include: { posts: true }
});
> **The Scenario:** It's Friday at 4 PM. A junior dev asks Claude Code to "build a user reporting dashboard." The AI starts writing terribly unoptimized loops. But because you installed this skill globally for the team, the AI reads your `SKILL.md`, sees the "BAD" example, and automatically rewrites the code to use a proper `include` statement. You get to go home on time.
## Step 3: Test the Skill Locally
Before you publish it, make sure the AI actually listens to it.
If you are using Cursor or Claude Code, you can load the skill directly from your local directory to see how the agent behaves.
```bash
npx skills add ./my-database-skillAsk the agent to write a query and see if it follows your rules. If it ignores them, your instructions in SKILL.md are probably too vague. Tighten them up.
Step 4: Publish Your Skill
Once it works, you want to share it. The easiest way is to push it to a public GitHub repository. The npx skills CLI natively understands GitHub paths.
- Commit the
my-database-skilldirectory to a new repo (e.g.,your-username/my-database-skill). - Tell your team to run:
npx skills add your-username/my-database-skillThe CLI will fetch the SKILL.md file and make it available to their local agents. When you push an update to the main branch, your team just runs npx skills update to get the latest rules.
What about Executable Tools?
If your skill needs to do something (like fetch live data from a third-party API), you don’t write complex internal classes. You expose a standard REST endpoint or an OpenAPI spec. The Vercel AI SDK handles the rest. We’ll cover how to wire those up in the next guide.
Next Step: Learn how to use these skills inside a custom application.
→ Read: How to Consume Vercel Skills in the AI SDK
