How to set up Claude skills_

Pick where the skill lives

Two options. Decide before you create the file.

Global skill — available in every project. Lives here:

~/.claude/skills/<skill-name>/SKILL.md

Project skill — scoped to one project, shared with the team via git. Lives here:

<project-root>/.claude/skills/<skill-name>/SKILL.md

Rule of thumb: personal preferences and cross-project habits go global. Team conventions, project context, and codebase-specific rules go in the project. Commit project skills to git so every teammate gets them on clone.

Write the frontmatter

Every SKILL.md starts with a YAML frontmatter block — that is how Claude Code knows what the skill is called and when to consider invoking it. The minimum looks like this:

---
name: writing-prs
description: Use when drafting pull request descriptions, summaries, or commit messages — encodes team voice and required sections.
---

Two fields, both required, both load-bearing.

name — the identifier. Match it to the directory name. Kebab-case, no spaces.

description — the trigger text. This is what Claude reads to decide whether your skill is relevant to the current task. Write it as you would describe the skill to a coworker: "Use when…" or "Triggers on…" patterns work well. Specific descriptions trigger more reliably than vague ones — "drafting PRs and commit messages" beats "code stuff."

Watch the YAML syntax. The opening and closing --- must each be on their own line. No leading whitespace. No tab characters inside the block. If the frontmatter is malformed, the whole skill is ignored without warning.

Copy these, adapt to your team

Example 1: writing-prs

File: .claude/skills/writing-prs/SKILL.md

---
name: writing-prs
description: Use when drafting pull request descriptions, commit messages, or PR summaries. Encodes team voice and required structure.
---

# Writing pull requests

Use this skill whenever the user asks for a PR description, commit message,
or summary of changes.

## Required structure

Every PR description has three sections, in this order:

1. **What changed** — one or two sentences, plain English.
2. **Why** — the problem this solves or the reason for the change.
3. **Test plan** — checklist of what to verify before merging.

## Voice rules

- Second person ("your team"), not first person ("we").
- Active voice.
- No filler words: "simply," "just," "basically."
- No emoji.
- No marketing language: "robust," "powerful," "seamless."

## Example

Bad:
> This PR refactors the auth module to be more robust and improves
> performance significantly.

Good:
> **What changed**
> Replaced the session lookup in `getCurrentUser()` with a single
> indexed query. Removed the in-memory cache that was no longer needed.
>
> **Why**
> The cache was a 2024 workaround for a slow query. The slow query is
> now fixed (issue #482), so the cache adds complexity without value.
>
> **Test plan**
> - [ ] Run integration tests
> - [ ] Verify session works for fresh login
> - [ ] Verify session works after server restart

Example 2: querying-customers-db

File: .claude/skills/querying-customers-db/SKILL.md — pairs with a Postgres MCP server.

---
name: querying-customers-db
description: Use when querying the customers database via the Postgres MCP server. Encodes table conventions, safe query patterns, and PII rules.
---

# Querying the customers database

Use this skill any time you query the customers Postgres database
through the connected MCP server.

## Tables you should know

- `customers` — primary, partitioned by `region`. Always filter by
  `region` to avoid full scans.
- `customer_pii` — contains raw email and phone. Read-only. Only query
  when the user explicitly asks for PII fields.
- `subscriptions` — joined to customers via `customer_id`.

## Always

- Filter by `created_at` when scanning recent data — never `SELECT *`
  without a date filter.
- Use `LIMIT` on exploratory queries; the customers table is large.
- Quote identifiers if they contain capitals or underscores.

## Never

- Run `UPDATE` or `DELETE` against this database. It is read-only.
- Join `customer_pii` to `customers` and return raw email in a CSV
  export — log the request and ask the user to confirm.

## Pagination pattern

For paginated reads, use keyset pagination on `id`:

```sql
SELECT id, name, created_at
FROM customers
WHERE region = 'us-east'
  AND id > $last_id
ORDER BY id
LIMIT 100;
```

Avoid OFFSET on this table — it gets slow past page 5.