ailiteracynepal 🇳🇵
Text size

Chapter 05 · Section III · 15 min read

Writing your first skill

A worked example — from noticing a repeated prompt shape to shipping a skill any teammate can invoke. If you follow along in your own repo, you will have a working /pr-summary skill by the end.

The clearest way to internalise skills is to write one. This section walks through a concrete example: turning “summarise the current branch’s changes into a short PR description” from a prompt you keep retyping into a /pr-summary command anyone on your team can invoke.

Step 1 — notice the pattern

The prompt in your head, every time you open a PR, is roughly:

“Look at the diff between this branch and main. Write a short PR description: one-paragraph summary, bullet list of the significant changes, and a test-plan checklist. Keep it under 200 words.”

You have typed some version of that a dozen times this month. That is the signal a skill is worth making.

Step 2 — create the directory

For a project-local skill (available inside this repo only):

mkdir -p .claude/skills/pr-summary
touch .claude/skills/pr-summary/SKILL.md

For a user-global skill (available in every project on your machine):

mkdir -p ~/.claude/skills/pr-summary
touch ~/.claude/skills/pr-summary/SKILL.md

Project-local is a good default for team-specific workflows; user-global is right for personal shortcuts.

Step 3 — write the SKILL.md

---
name: pr-summary
description: >
  Draft a short PR description from the current branch's diff against main.
  One-paragraph summary + bullet list of significant changes + test-plan checklist.
argument-hint: (optional) base branch to diff against; defaults to `main`
---

# PR summary

You are drafting a pull request description for the current git branch.

1. Determine the base branch: use the argument if provided, otherwise `main`.
2. Run `git diff <base>...HEAD` to see the full range of changes.
3. Run `git log <base>..HEAD --oneline` for commit context.
4. Produce a description in this exact shape:

   ## Summary
   One paragraph. Focus on the "why", not the "what".

   ## Changes
   - Bullet list of significant changes (file paths in backticks).
   - Group related edits.

   ## Test plan
   - [ ] Manual step 1
   - [ ] Manual step 2
   - [ ] Automated: `<command that verifies>`

Keep the whole description under 200 words. Do not include a "Generated by Claude" line.

Step 4 — try it

Restart Claude Code, or run /help — the new skill should appear.

/pr-summary

Claude reads the diff, follows the checklist, and returns a formatted description. Copy-paste into your PR.

Step 5 — iterate

Almost every skill improves on its second and third use. Common tweaks:

  • Tighten the output shape. If Claude keeps producing descriptions that are too long or the wrong tone, spell out the constraint more precisely.
  • Add an example. Paste a real, good PR description into the skill body and say “produce output in this shape.”
  • Handle edge cases. “If the branch has zero commits ahead of the base, say so and stop.”

Sharing

If the skill is in .claude/skills/, it is committed with the repo — teammates who pull will have it too. Nothing else to do.

Check your understanding

Quick check

—

You just wrote a project-local /pr-summary skill. Where does it live so your teammates get it when they pull the repo?