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