Building your first AI coding skill

Step 1, Pick a real workflow

Skills are at their best when they encode something you already do and are tired of re-explaining. Don't write a generic "best practices for TypeScript" skill, the model already has those. Write the thing your team actually argues about: how to structure a new domain module, how to write a migration, how to phrase an ADR.

For this tutorial we'll write a small skill called prisma-select-only. The rule: when generating Prisma queries, always use select, never include, and explicitly list the fields. Small, opinionated, easy to verify.

Step 2, Write the SKILL.md

Create a folder and a single file:

mkdir -p skills/prisma-select-only
$EDITOR skills/prisma-select-only/SKILL.md

Then write this:

---
name: prisma-select-only
description: When writing Prisma queries, always use `select` (not `include`) and list fields explicitly.
license: MIT
version: 0.1.0
tags: [prisma, database, conventions]
---

# Prisma: select, not include

We always use `select` to fetch only the fields we need. Reasons:

1. Prevents accidental over-fetching of PII (email, hashed passwords).
2. Makes the read shape obvious in code review.
3. Forces a thought about indexes and column count.

## Rules

- Never use `include`. Replace with nested `select`.
- Always list scalar fields explicitly. Don't rely on defaults.
- For relations, use `select: { user: { select: { id: true, name: true } } }`.

## Example

```ts
// ❌ Don't
const post = await db.post.findUnique({
  where: { id },
  include: { author: true },
});

// ✅ Do
const post = await db.post.findUnique({
  where: { id },
  select: {
    id: true,
    title: true,
    author: { select: { id: true, name: true } },
  },
});
```

Two things matter most. The description is what the model sees first, write it like a search query, not a tagline. And the body should be operational, not aspirational. "Always use select" is operational. "Write better queries" is not.

Step 3, Validate it locally

The skills-hub CLI ships a parser and validator. Run it against your file before you go anywhere else:

npx @skills-hub-ai/cli validate skills/prisma-select-only/SKILL.md

The validator checks frontmatter (name and description are required, name must be kebab-case), warns on missing license or version, flags suspiciously short bodies, and runs the same security scan the public registry uses, secrets, dangerous shell, prompt-injection smells.

Then dogfood it. Drop the file into .claude/skills/prisma-select-only/SKILL.md and ask Claude Code to "write a Prisma query that fetches a post with its author." If the skill fires, you'll see it pulled into context and the output will use select. If it doesn't fire, your description isn't matching, tighten it.

Step 4, Iterate against real prompts

Treat the skill like a prompt eval. Pick five or six prompts your team actually sends ("add a new endpoint that returns paginated posts," "write a query for the user's recent activity"), run them with and without the skill loaded, and compare. You're looking for two failure modes:

• Doesn't fire. The description doesn't sound like the user's prompt. Add task-shaped phrases ("when generating", "when writing", "when fetching") and the names of the technologies involved.
• Fires but ignored. The body is too long, too abstract, or buried. Move the rule to the top, lead with a concrete example, cut everything that isn't actionable.

Existing high-quality skills are good models for shape. Read test-driven-development, code-review-and-quality, and documentation-and-adrs , they're tight, opinionated, example-led.

Step 5, Publish via /publish

When the skill survives a few real prompts, publish it. From the directory containing your SKILL.md:

npx @skills-hub-ai/cli login          # GitHub OAuth, one time
npx @skills-hub-ai/cli publish ./skills/prisma-select-only

Or use the web flow at skills-hub.ai/publish: paste a public GitHub URL pointing at your SKILL.md, review the parsed metadata and security scan, and submit. The platform assigns a slug under your username, runs a fresh scan, and publishes a detail page within seconds. Patches bump the version on re-publish; breaking changes get a major bump.

Step 6, Install it everywhere

Once it's published, anyone (including future you on a different machine) can install:

npx @skills-hub-ai/cli install <username>/prisma-select-only \
  --target claude-code,cursor

That's the loop. Pick a real workflow, write the smallest useful SKILL.md, validate it, dogfood it, publish it, and let .skills.json keep the team in sync.

Keep going

• Install Claude skills in 30 seconds
• Claude Code skills vs Cursor rules
• The SKILL.md format spec
• Publish a skill