Skip to content
Back to search

how-to-build-a-skill

MarketplaceWorks with Claude CodeGitHub

Build Claude Code skills from a process you already ran: the guide, the format, a template, and two skills that create and review skills.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/unclegian--how-to-build-a-skill/badge.svg)](/listings/unclegian--how-to-build-a-skill)

HTML

<a href="/listings/unclegian--how-to-build-a-skill"><img src="/api/listings/unclegian--how-to-build-a-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines
  1. {
  2. "name": "how-to-build-a-skill",
  3. "owner": {
  4. "name": "Gianluca D'Auria",
  5. "email": "gianluca@trygaja.com"
  6. },
  7. "plugins": [
  8. {
  9. "name": "how-to-build-a-skill",
  10. "source": "./",
  11. "description": "create-skill and review-skill, on the format of the How to build a skill guide."
  12. }
  13. ]
  14. }
README.md · README · 257 lines
  1. # How to build a skill
  2. This guide takes you from a process you run by hand to a Claude skill that runs it the same way every time, in ten steps. It is the format we use at [gaja](https://trygaja.com) for the skills we run every day, with a template to copy and a complete skill to read.
  3. - **The guide**: this page.
  4. - **The format**: [SKILL-FORMAT.md](SKILL-FORMAT.md), every rule in one place.
  5. - **The template**: [template/my-skill/](template/my-skill/), an empty skill with every folder.
  6. - **The example**: [examples/skills/process-call/](examples/skills/process-call/), a skill that turns a call transcript into a summary, with variants, scripts and evals.
  7. - **Two skills that do this for you**, installable as a Claude Code plugin:
  8. - `create-skill` turns a process you already ran by hand into a skill folder on this format.
  9. - `review-skill` checks any skill, yours or someone else's, on format and security before you install it.
  10. ```
  11. /plugin marketplace add unclegian/how-to-build-a-skill
  12. /plugin install how-to-build-a-skill@how-to-build-a-skill
  13. ```
  14. ---
  15. ## 1. What a skill is
  16. Anthropic's definition: *"Skills are folders of instructions, scripts, and resources that Claude loads dynamically to improve performance on specialized tasks. Skills teach Claude how to complete specific tasks in a repeatable way."* ([What are skills](https://support.claude.com/en/articles/12512176-what-are-skills))
  17. Claude reads the name and the description of every skill it has. When a request matches one, it loads the rest of the folder. That is why a skill costs little while it waits, and why the description decides whether it ever runs.
  18. How it differs from what you already use:
  19. - **MCP** connects Claude to a tool. A skill teaches Claude how to use that tool for your process.
  20. - **Custom instructions and `CLAUDE.md`** apply to every conversation. A skill loads only for its task.
  21. Our own definition adds one line: **a skill is a process of yours, with one job and one output in a place it names.**
  22. ## 2. Run it by hand first
  23. A skill written before any real run has none of the corrections that make it work. So before writing anything, do the task with Claude in a normal chat, on real inputs, more than once. Correct it as you go and keep notes on:
  24. - the steps that worked, in the order they worked
  25. - every correction you made, and what Claude did before it
  26. - what the input looked like, and what a good output looks like
  27. - the facts about your company you had to tell Claude
  28. The first three become the skill. The fourth becomes knowledge, step 3.
  29. Then keep iterating. A skill is worth keeping when it is your process, run and corrected enough times that a run comes out right without you touching it.
  30. ## 3. The method in the skill, the knowledge outside
  31. A skill carries the **method**: the order of the steps, what to check, when to stop, the shape of the output. It never carries the **knowledge**: your ICP, your prices, your deal stages, your tone of voice, your team, your channels.
  32. The test is one question:
  33. > If I changed company tomorrow, would this line change?
  34. | Answer | It is | It lives in |
  35. |---|---|---|
  36. | No | method | the skill |
  37. | Yes | knowledge | your knowledge base, a folder of markdown files the skill opens |
  38. A skill that holds knowledge breaks quietly. Your prices change, you update the prices page, and the skill that copied them keeps quoting the old ones until a customer reads the wrong number.
  39. Kept apart, the skill is invariant: the same `process-call` runs in any company, and what changes is the knowledge it opens. In the example, how to read a prospect call is in the skill, and the deal stages it maps the call to are in `knowledge/deal-stages.md`.
  40. A second test for any file inside the folder: **delete the skill, is the file still true?** If yes, it is knowledge and it moves out.
  41. ## 4. The folder
  42. ```
  43. my-skill/
  44. ├── SKILL.md required, the path, under 200 lines
  45. ├── evals/ required, the test cases
  46. ├── memory.md required, what real runs taught
  47. ├── variants/ one file per situation
  48. ├── schemas/ the shape of the output, shared blocks
  49. ├── scripts/ the deterministic steps, as code
  50. ├── worked-examples/ a real example of the bar to meet
  51. └── prompts/ prompts only this skill uses
  52. ```
  53. Three files are required, the rest only when the skill needs them. Copy [template/my-skill/](template/my-skill/) into `.claude/skills/` in your project, or `~/.claude/skills/` for every project, and rename it.
  54. ## 5. SKILL.md
  55. ### The frontmatter
  56. Each field answers a question someone will ask about the skill. A few are read by Claude to decide when and how to run it. The others describe the skill to you, your team and your tools. Every field is in the [template](template/my-skill/SKILL.md).
  57. | Field | Answers | Read by |
  58. |---|---|---|
  59. | `name` | what it is called: a verb, kebab-case, the same as the folder | Claude |
  60. | `description` | what it does and when Claude should run it: verb first, the main use case first, and a `Not for:` line | Claude |
  61. | `when_to_use` | the phrases a user types, in any language | Claude |
  62. | `model` | the model to switch to while the skill runs, optional | Claude |
  63. | `goal` | the intent, in one line | you |
  64. | `outcome` | the exact path of what it writes | you |
  65. | `inputs` | what it needs: `required` stops the run when missing, `recommended` lets it continue and flag the gap | you |
  66. | `tier` | who it serves: `personal`, `shared` with the team, or `infrastructure` when it writes a system everyone uses | you |
  67. | `validation` | how you know it works: `verifiable` by its evals, or `outcome-anchored` when only results over weeks can tell | you |
  68. | `status` | `draft`, `active`, `deprecated`, moved by a person, never by a date | you |
  69. | `mcps_used` | the tools it calls | you |
  70. | `feeds_into` | the skills that read its output | you |
  71. The `description` and `when_to_use` together stay under 1,536 characters. When in doubt, describe more: a skill that never fires is worse than one that fires too often.
  72. **Where you run the skill decides which fields it can carry:**
  73. | You run it in | The frontmatter |
  74. |---|---|
  75. | Claude Code, in the terminal or an IDE such as VS Code | every field above loads. Claude skips the ones it does not use, without errors |
  76. | claude.ai or the Skills API | only `name`, `description`, `license`, `compatibility`, `metadata` and `allowed-tools`. Any other field stops the upload with an error, so the phrases of `when_to_use` move into `description` |
  77. ### The body
  78. The body is a **path**: the steps Claude walks, and the files it opens on the way. Three sections, always in this order:
  79. 1. `## How it works`, the stops, numbered from 0
  80. 2. `## Output`, the exact path, and what happens when the skill stops
  81. 3. `## References`, every file the skill opens, one line each
  82. When to use the skill, and when not, lives in the frontmatter only. Claude loads the body after it has picked the skill, so a `## When to use` section there never helps it pick: Anthropic's own skill-creator puts all of it in the description.
  83. Keep it under 200 lines. A longer body is carrying knowledge or examples that belong in another file. While you write it:
  84. - **Cut what Claude already knows.** For each line ask: would Claude get this wrong without it? If not, delete it.
  85. - **Give a default, never a menu.** "Use X. For scanned files, use Y."
  86. - **Explain the why** in one clause. Claude applies a rule better when it knows what the rule protects.
  87. ### Stopping is an outcome
  88. Every skill writes its output where `outcome` says, or it stops and says why. A missing required input, an ambiguous case, a duplicate: each one ends the run with a one-line STOP record, never with an empty or invented output.
  89. ## 6. Variants
  90. Some processes look the same and are not. A call with a prospect and a call with a customer follow the same spine and look for different things.
  91. When the difference is in the input only, one file takes it as a parameter. When the fields, the checks or the output sections differ, each situation gets its own file in `variants/`:
  92. ```
  93. variants/
  94. ├── prospect.md
  95. ├── customer.md
  96. └── internal.md
  97. ```
  98. - **The folder is the list.** Nothing else declares the variants, so nothing can disagree with them.
  99. - **Stop 0 picks one** and the skill opens only that file.
  100. - **A skill with one situation** keeps its steps in `SKILL.md` and has no `variants/`.
  101. ## 7. Scripts
  102. If the same input always gives the same output, it is a script: dates, paths, counts, exact matches, format checks. Judgment stays in `SKILL.md`: which variant, what matters, what to write.
  103. The signal is Claude rebuilding the same logic on every run, or getting a mechanical step wrong once in ten. The example has three scripts:
  104. | Script | What it does | The mistake it removes |
  105. |---|---|---|
  106. | `lookback.py` | finds earlier summaries with the same counterpart, refuses a second summary of the same call | a lost thread, a duplicate file |
  107. | `new_summary.py` | builds the path from the date of the call and writes the empty summary | a call from October filed in November |
  108. | `check_summary.py` | checks every quote word for word against the transcript, the sections, the length, the dates, no email or phone number | invented quotes, a renewal dated in the wrong year, summaries three times too long, personal data |
  109. The last one runs as a **validation loop**: check, fix what it prints, check again, deliver only when it passes.
  110. ## 8. Evals
  111. Evals are the proof that the skill works, and that it does better than Claude without it. Claude Code runs them with [`claude plugin eval`](https://code.claude.com/docs/en/plugin-evals): each case is a folder with the task as a user would type it, and the graders that score the result.
  112. ```
  113. evals/01-prospect-discovery/
  114. ├── prompt.md
  115. └── graders/
  116. ├── file.md did the summary land at the right path?
  117. ├── check-ran.md did the check script run?
  118. └── quotes.md are the quotes word for word?
  119. ```
  120. Two kinds of grader, for two kinds of question:
  121. - **Rules** for the form: a regex on the output, a file that must exist, a script that must run. Free, and the same answer every time.
  122. - **An LLM judge** for the substance: the quotes are real, nothing is invented, the right variant was picked. One claim per judge: in our first run a judge asked four things at once failed a correct summary.
  123. Write 10 to 15 cases, one for each mistake you have seen. Two or three on day one are fine, as long as they run. Each case runs with and without the skill, and the difference in score is what the skill adds.
  124. ```bash
  125. cd examples/skills/process-call
  126. claude plugin eval . --allow-tools Bash Write Edit --scaffold --no-publish
  127. ```
  128. One run of the 10 example cases on Sonnet takes about two minutes and costs about $1.40. The same command runs the cases of `skills/create-skill` and `skills/review-skill`, from their folders.
  129. A skill whose result only shows over weeks, like an outreach sequence, is `outcome-anchored`: its evals certify the form, and the replies decide the rest.
  130. ## 9. Iterate
  131. Every run that needs a correction teaches the skill something. `memory.md` is where it goes:
  132. - **Read at stop 0**, so the next run starts from what the last one learned.
  133. - **Written** when you correct a run, when the skill stops, or when a run shows something new. One dated line each.
  134. - **A lesson that comes back** stops being a line in memory and becomes a step in `SKILL.md`, a script, or an eval case.
  135. | What happens | What you change |
  136. |---|---|
  137. | you correct a run | a line in `memory.md` |
  138. | the same correction twice | a step in `SKILL.md`, or a script |
  139. | a new kind of mistake | an eval case that catches it |
  140. | the skill does not fire, or fires on the wrong request | the `description` |
  141. `status` moves to `active` when a person has seen it run with its evals passing.
  142. A real loop from the example. The evals caught a summary writing a deadline the call never set, and a line in `memory.md` fixed it for the next runs. A later run wrote another invented deadline, and dated a renewal "on the first of March", said in November, in the current year. The same correction twice, so it became code: `check_summary.py` now fails a step dated before the call, and a next step with no date.
  143. ## 10. Chains
  144. Some processes are several skills in a row: one produces what the next consumes. Write that order in a **chain**, also called an SOP, and keep it free of logic.
  145. | # | Skill | Hands to the next |
  146. |---|---|---|
  147. | 1 | `list-build` | a list of accounts |
  148. | 2 | `icp-qualifier` | the accounts that fit your ICP |
  149. | 3 | `research` | a brief per account |
  150. | 4 | `outreach` | the first message |
  151. - **The chain orders the skills, each skill orders its stops.** A rule written in the chain is a rule the skill does not know.
  152. - **Each step names its skip condition**, and a skip is recorded.
  153. - **Write it after you walked it**, like a skill: a chain you only imagined has the same problem as a skill you only imagined.
  154. ---
  155. ## Before you ship
  156. Ask `review-skill` to review it, or walk [SKILL-FORMAT.md](SKILL-FORMAT.md) section 9 by hand: one checklist for the frontmatter, the folder, the body and the evals.
  157. Do the same before installing a skill you did not write. A skill runs with your permissions, so `review-skill` reads every file for hidden instructions, secrets read and data sent out, and never runs any of them. Its verdict is one of three: install, fix first, or do not install.
  158. ## The Skill kit
  159. This repository is one of four:
  160. - How to build a skill: this one.
  161. - [Claude personal memory](https://github.com/unclegian/claude-personal-memory): a small personal brain in plain files you own. Claude remembers who you are, your goals and what you corrected.
  162. - [Claude Code daily](https://github.com/unclegian/claude-code-daily): the Claude Code tools I use every day, by category, with the install lines.
  163. - [Claude antislop](https://github.com/unclegian/claude-antislop): keeps the tells of AI writing out of what Claude writes, with a list of 61 patterns, hooks that check every file and reply, and a skill that rewrites a draft until it is clean.
  164. <!-- CTA -->
  165. ---
  166. ## Want skills like these built on your team's processes?
  167. At gaja we build two things for go-to-market teams:
  168. - **The knowledge your Claude reads**: your ICP, your deal stages, your objections, your voice, built from your calls, docs, tools and team.
  169. - **The shared skills your team runs**: written on the processes you already follow, deployed to the whole team, all reading the same knowledge.
  170. Get in touch:
  171. - Gianluca D'Auria, Co-founder at gaja: gianluca@trygaja.com, [LinkedIn](https://www.linkedin.com/in/gianlucadauria-gaja/)
  172. - gaja: [trygaja.com](https://trygaja.com), [LinkedIn](https://www.linkedin.com/company/gaja-brain/)
  173. MIT licence.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.