Turn a prompt you keep repeating into a skill

The steps

One step at a time. When a step’s check matches, tick it and the next one opens.

1. 01

   Step 1 of 7: Pick a prompt you keep repeating

   Choose instructions you paste again and again that should give the same kind of answer every time.

   A skill is a saved set of instructions in a file called SKILL.md. You run it by typing its name, like /client-update. Claude can also use it on its own when your request matches what the skill says it is for.

   A prompt is worth turning into a skill when:

   • You have pasted the same instructions more than twice.
   • The answer should come back in the same shape every time, such as the same headings or the same checklist.
   • It is a procedure you run now and then, not a fact Claude needs in every session.

   Note: Skill or CLAUDE.md? CLAUDE.md loads at the start of every session, so keep it for facts and rules that always apply. A skill’s body loads only when it is used, so a long procedure costs almost nothing until you need it.

   Today’s example comes up for anyone who builds for clients: a short update that turns your commits into plain English, under the same three headings every time: Shipped, In progress and Needs your input.

   For “My own project”

   Got a repeated prompt of your own in mind? Write it down, but build client-update first. It works in any project with git history, and the last step shows you how to turn the same pattern into your own skill.

   Check it worked

   You can finish this sentence for your prompt: “It writes ___, and I ask for it when ___.” For today’s skill: “It writes a plain-English client update from recent commits, and I ask for it when a client wants to know what changed.” That sentence is what the skill’s description will say.

   It worked — next step Not yet
2. 02

   Step 2 of 7: Give the project a git history

   The skill writes its update from your commits, so the project needs to be a git repository with at least one commit.

   Open a terminal in the project’s top folder, the one with README.md in it. First see whether git is already set up there:

   Terminal or PowerShellCopy

   git log --oneline -3

   If that lists commits, this step is done. If git says the folder is not a git repository, or that your branch does not have any commits yet, run these three commands:

   Terminal or PowerShellCopy

   git init
   git add .
   git commit -m "Start Acme Quotes"

   git init may print a few hint lines about the default branch name. You can ignore them. In a folder git already knows, it says it reinitialized the repository instead, which is safe.

   For “The practice project from Day 1”

   Use the same Acme Quotes folder you worked in on Day 1.

   For “A fresh copy of the practice project”

   Download and unzip the Day 1 kit first. Then open the terminal in the folder that holds README.md and package.json. On Windows, Extract All can put that folder inside another folder with the same name, so look one level down.

   For “My own project”

   Your project is probably in git already, so git log lists commits and you can move on. If it isn’t, run the same three commands with a commit message of your own.

   Check it worked

   Terminal or PowerShellCopy

   git log --oneline

   You see at least one line: a short code followed by the commit message, such as Start Acme Quotes.

   If it didn’t work

   Git says “Author identity unknown” and asks who you are

   Git needs a name and an email for every commit. Set them with your own details, then run the commit again. Leave out --global to set them for this project only.

   Terminal or PowerShellCopy

   git config --global user.name "Your Name"
   git config --global user.email "[email protected]"
   git commit -m "Start Acme Quotes"

   The terminal says git isn’t found or isn’t recognised

   For macOS

   Install Apple’s command line tools, which include git. If you use Homebrew, brew install git works too.

   TerminalCopy

   xcode-select --install

   For Linux and WSL

   On Ubuntu or Debian, install it with apt. On other distributions, use your package manager.

   TerminalCopy

   sudo apt install git

   For Windows

   Install Git for Windows, then close PowerShell and open a new window so it finds git.

   PowerShellCopy

   winget install --id Git.Git -e --source winget

   Then run git --version. It prints a version number.

   Windows shows “LF will be replaced by CRLF” warnings

   Those are warnings, not errors. Git for Windows converts line endings by default, and the commit still goes through. Run git log --oneline to confirm it.

   It worked — next step Not yet Back
3. 03

   Step 3 of 7: Create the skill folder

   Make a folder called client-update in a skills folder; the folder’s name becomes the command you type.

   Every skill is a folder with a SKILL.md file inside. The folder’s name is the command, so client-update gives you /client-update. Keep names short, lowercase and joined with hyphens, since you will type them.

   Where the folder lives decides who gets the skill:

   • .claude/skills/<name>/ inside a project: for everyone who works in that project, once you commit it.
   • ~/.claude/skills/<name>/ in your home folder: for you, in every project on this computer. On Windows that’s %USERPROFILE%\.claude\skills\<name>\.

   For “Everyone on this project”

   Run this in the project’s top folder. It creates the folder, then lists what is in .claude/skills.

   For macOS, Linux and WSL

   TerminalCopy

   mkdir -p .claude/skills/client-update
   ls .claude/skills

   For Windows

   PowerShellCopy

   New-Item -ItemType Directory -Force -Path .claude\skills\client-update
   Get-ChildItem .claude\skills

   For “Just me, in every project”

   Run this from any folder. It creates the folder in your home folder, then lists your personal skills.

   For macOS, Linux and WSL

   TerminalCopy

   mkdir -p ~/.claude/skills/client-update
   ls ~/.claude/skills

   For Windows

   PowerShellCopy

   New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\skills\client-update"
   Get-ChildItem "$env:USERPROFILE\.claude\skills"

   Check it worked

   The listing shows a folder named client-update. Other skill folders may sit next to it, which is fine.

   If it didn’t work

   The folder was created somewhere else

   Folder commands work from wherever your terminal is. Run pwd (it works in PowerShell too) to see where you are, cd into the project’s top folder and run the command again. Then delete the stray folder.

   You can’t see the .claude folder in Finder or your file manager

   Folders whose names start with a dot are hidden by default on macOS and Linux. In Finder, press Cmd+Shift+. (full stop) to show them. The terminal listing is the check that counts.

   It worked — next step Not yet Back
4. 04

   Step 4 of 7: Write SKILL.md

   Save the skill’s instructions in SKILL.md: a short header that tells Claude when to use it, then the steps it follows.

   Create SKILL.md in the client-update folder and paste in the file below with its copy button. Any code editor works, such as VS Code. There are terminal commands for it at the end of this step too.

   .claude/skills/client-update/SKILL.md · MarkdownCopy

   ---
   description: Writes a short plain-English progress update for a non-technical client from recent git commits, always under the headings Shipped, In progress and Needs your input. Use when the user asks for a client update, a status update, a weekly summary or what changed this week.
   argument-hint: "[optional notes, such as since Monday or waiting on logo files]"
   ---
   
   Write a progress update for a client who doesn't read code.
   
   ## Gather the facts
   
   1. Run this command in the project folder:
      `git log --since="7 days ago" --no-merges --date=short --format="%h %ad %s"`
      If the notes at the end name a different period, such as "since Monday" or
      "last two weeks", change `--since` to match.
   2. If git reports that this isn't a git repository, or that there are no
      commits yet, tell the user that and stop. Don't write an update from guesses.
   3. If the log is empty, say nothing was committed in that period and offer to
      look further back.
   4. If a commit message is unclear, run `git show --stat <hash>` to see what it
      touched. Use it to understand the change, not to quote it.
   
   ## Write the update
   
   Use these three headings, in this order, every time. Keep a heading even when
   its section is empty.
   
   ```
   ## Shipped
   ## In progress
   ## Needs your input
   ```
   
   - **Shipped**: finished work, described by what the client can now do or see.
     Write "Quotes now show VAT on its own line", not "refactored buildQuote".
   - **In progress**: work that is started but not finished, such as commits
     marked WIP, plus anything the notes say is under way.
   - **Needs your input**: decisions or material only the client can give. If
     there are none, write "Nothing right now."
   
   Rules:
   
   - One bullet per change, one sentence each. Merge related commits into one bullet.
   - No commit hashes, file names, branch names or developer terms such as
     refactor, merge, PR, endpoint or deploy.
   - Only report what the commits and notes show. Never add results, numbers or
     dates that aren't there.
   - Under 150 words in total. Friendly and plain. No greeting or sign-off unless
     the user asks for one.
   
   For the tone and length to aim for, see [example.md](example.md).
   
   ## Notes from the user
   
   These may be empty. Use them for the period, for work in progress and for
   questions to put to the client.
   
   $ARGUMENTS
   

   Name it SKILL.md, in capitals. For a personal skill, it goes in ~/.claude/skills/client-update/, which on Windows is %USERPROFILE%\.claude\skills\client-update\.

   What each part does:

   • The first line must be exactly ---. Claude Code reads the header, called the frontmatter, only when --- is the very first line. With anything above it, even a blank line, the whole file is treated as plain instructions.
   • description is how Claude decides when to use the skill. It says what the skill does first, then the requests that should trigger it.
   • argument-hint shows as you type /client-update, a reminder that it takes optional notes.
   • The body is the prompt you would otherwise paste: where to get the facts, the three fixed headings and the rules for plain English.
   • $ARGUMENTS at the end is where Claude Code puts whatever you type after the command, such as notes about the week.

   Warning: Field names must match exactly, hyphens included. Claude Code ignores a field it doesn’t recognise without telling you, so argument_hint simply does nothing.

   Now save the example next to it. SKILL.md links to it, so Claude can read it for tone and length when it writes an update. Long examples and reference notes belong in files like this, not in SKILL.md itself.

   .claude/skills/client-update/example.md · MarkdownCopy

   # Example client update
   
   A made-up update for Acme Quotes. Match its tone, length and headings, not its
   content: every update must come from the real git log and the user's notes.
   
   ## Shipped
   
   - Quotes now list the discount and the amount after discount on separate lines,
     so it's clear what the client saves.
   - Typing a role that isn't on the rate card now gives a clear error instead of
     a confusing total.
   
   ## In progress
   
   - A printable version of the quote. The layout is done and the totals are
     being checked.
   
   ## Needs your input
   
   - Should repeat clients get a standing discount? If so, what percent?
   

   For “The practice project from Day 1” or “A fresh copy of the practice project”

   Note: Short on time? The finished Day 2 kit has both files in .claude/skills/client-update/. Making them yourself is how the parts stick, though.

   For “Everyone on this project”

   No editor handy? Save the files from the project’s top folder:

   For macOS

   Copy a file with its copy button, then run the matching command. It writes what you copied straight into the file.

   After copying SKILL.mdCopy

   pbpaste > .claude/skills/client-update/SKILL.md

   After copying example.mdCopy

   pbpaste > .claude/skills/client-update/example.md

   For Linux and WSL

   Open each file in nano, paste (Ctrl+Shift+V in most terminals), then press Ctrl+O, Enter and Ctrl+X to save and close.

   SKILL.mdCopy

   nano .claude/skills/client-update/SKILL.md

   example.mdCopy

   nano .claude/skills/client-update/example.md

   For Windows

   Open each file in Notepad. If Notepad asks whether to create the file, choose Yes. Paste, save with Ctrl+S and close.

   SKILL.mdCopy

   notepad .claude\skills\client-update\SKILL.md

   example.mdCopy

   notepad .claude\skills\client-update\example.md

   For “Just me, in every project”

   No editor handy? Save the files into your personal skill folder:

   For macOS

   Copy a file with its copy button, then run the matching command. It writes what you copied straight into the file.

   After copying SKILL.mdCopy

   pbpaste > ~/.claude/skills/client-update/SKILL.md

   After copying example.mdCopy

   pbpaste > ~/.claude/skills/client-update/example.md

   For Linux and WSL

   Open each file in nano, paste (Ctrl+Shift+V in most terminals), then press Ctrl+O, Enter and Ctrl+X to save and close.

   SKILL.mdCopy

   nano ~/.claude/skills/client-update/SKILL.md

   example.mdCopy

   nano ~/.claude/skills/client-update/example.md

   For Windows

   Open each file in Notepad. If Notepad asks whether to create the file, choose Yes. Paste, save with Ctrl+S and close.

   SKILL.mdCopy

   notepad "$env:USERPROFILE\.claude\skills\client-update\SKILL.md"

   example.mdCopy

   notepad "$env:USERPROFILE\.claude\skills\client-update\example.md"

   Check it worked

   List the folder, then print the first line of SKILL.md:

   For macOS, Linux and WSL

   Project skillCopy

   ls .claude/skills/client-update
   head -n 1 .claude/skills/client-update/SKILL.md

   Personal skillCopy

   ls ~/.claude/skills/client-update
   head -n 1 ~/.claude/skills/client-update/SKILL.md

   For Windows

   Project skillCopy

   Get-ChildItem .claude\skills\client-update
   Get-Content .claude\skills\client-update\SKILL.md -TotalCount 1

   Personal skillCopy

   Get-ChildItem "$env:USERPROFILE\.claude\skills\client-update"
   Get-Content "$env:USERPROFILE\.claude\skills\client-update\SKILL.md" -TotalCount 1

   The listing shows SKILL.md and example.md, and the last line printed is the start of the header:

   The first line of SKILL.md

   ---

   If it didn’t work

   The first line isn’t ---

   Open SKILL.md and delete everything above ---: often a blank line, or extra text picked up by the copy. Save and print the first line again.

   The listing shows SKILL.md.txt or another extra extension

   Your editor added its own extension. Rename the file. For a personal skill, use the folder in your home folder instead.

   For macOS, Linux and WSL

   TerminalCopy

   mv .claude/skills/client-update/SKILL.md.txt .claude/skills/client-update/SKILL.md

   For Windows

   PowerShellCopy

   Rename-Item .claude\skills\client-update\SKILL.md.txt SKILL.md

   A file saved as rich text, such as SKILL.md.rtf, has formatting mixed into it. Delete it and make it again in a plain-text editor or with the commands above.

   It worked — next step Not yet Back
5. 05

   Step 5 of 7: Run /client-update yourself

   Start Claude Code in the project and type the command; the update comes back under the three headings.

   Start Claude Code in the project’s top folder:

   Terminal or PowerShellCopy

   claude

   If Claude Code asks whether you trust this folder, confirm it. It is your project.

   Was Claude Code already running before you made the skills folder? Then run /reload-skills so it sees the new folder. Claude Code doesn’t watch a folder made mid-session, so until you restart it, run /reload-skills again after each edit to SKILL.md. In a session started after the folder existed, edits show up on their own.

   Now run the skill. Claude reads the git log, then writes the update.

   In Claude CodeCopy

   /client-update

   Then try it with notes. Everything after the name goes where $ARGUMENTS sits in the skill:

   In Claude CodeCopy

   /client-update since Monday, still waiting on the logo files from the client

   The skill only reads the git log. If Claude Code asks before running a git command, allow it.

   Check it worked

   • Run /skills and type client: client-update is in the list. Press Esc to close it, not Enter, which changes the skill’s visibility.
   • The reply has three headings in this order: Shipped, In progress, Needs your input.
   • There are no commit hashes or file names in it, and after the second run the logo files appear under Needs your input.

   If it didn’t work

   /client-update isn’t in the menu, or Claude Code doesn’t recognise it

   • For a project skill, start Claude Code in the folder that holds .claude, or a folder inside it.
   • Run /reload-skills. It reports how many skills it found.
   • Check the names: the folder is client-update and the file is SKILL.md, in capitals.

   Claude says this isn’t a git repository, or there are no commits

   That is the skill doing its job: it stops instead of guessing. Go back to Give the project a git history, then run /client-update again.

   You edited SKILL.md but the reply hasn’t changed

   If you made the skills folder while Claude Code was running, run /reload-skills first, because Claude Code isn’t watching that folder for edits. A skill that already ran also stays in the conversation as it was, so run /clear to start a fresh conversation, then /client-update again.

   The skill disappeared after you used /skills

   In /skills, Space or Enter changes a skill’s visibility and Esc saves the change. Open /skills again, highlight client-update and press Space until it is back on, then press Esc.

   It worked — next step Not yet Back
6. 06

   Step 6 of 7: Let Claude use it without the command

   Ask in plain words; when your request matches the skill’s description, Claude loads the skill by itself.

   Claude sees a list of your skills with their descriptions, and loads the full skill when a request matches. Start a fresh conversation first, so the copy of the skill from the last step isn’t already in it:

   In Claude CodeCopy

   /clear

   Then ask the way you would ask a colleague:

   Paste into Claude CodeCopy

   What did we get done on this project this week? Write it up so I can send it to the client.

   Claude Code may ask before Claude uses the skill. Allow it.

   Check it worked

   The reply uses the skill’s three headings, Shipped, In progress and Needs your input, even though you never typed /client-update. To see the skill being called, press Ctrl+O to open the transcript viewer, which shows the tools Claude used. Press Ctrl+O again to close it.

   If it didn’t work

   Claude answered without the three headings

   Ask Claude what it has available:

   Paste into Claude CodeCopy

   What skills are available?

   If client-update is listed with your description, your request didn’t match it closely enough. Use its words, such as client update or weekly summary, or rewrite the description so it leads with the words you use. Then /clear and ask again. You can always run it by name with /client-update.

   If it isn’t listed, or is listed without your description, its visibility may have changed in /skills. Open /skills, highlight client-update and press Space until it is back on, then press Esc.

   If it is on but the description still isn’t the one you wrote, the header may not have parsed. /client-update still runs in that case, but Claude can’t match a request to it. Check the header with Claude Code’s validator in a terminal. It needs Claude Code v2.1.233 or later.

   For macOS, Linux and WSL

   Project skillCopy

   claude plugin validate .claude/skills

   Personal skillCopy

   claude plugin validate ~/.claude/skills

   For Windows

   Project skillCopy

   claude plugin validate .claude\skills

   Personal skillCopy

   claude plugin validate "$env:USERPROFILE\.claude\skills"

   When it finds a problem, it names the file and says what is wrong. Fix that line, save, then /clear and ask again.

   Claude uses the skill when you didn’t ask for an update

   Make the description say more precisely when to use it. If you only ever want to run it yourself, add disable-model-invocation: true, as the next step shows.

   It worked — next step Not yet Back
7. 07

   Step 7 of 7: Make it yours and share it

   Turn the same pattern into skills for your own repeated prompts, and commit project skills so your team gets them.

   Three changes cover most real use:

   1. Your own prompt. Copy the client-update folder and rename the copy; the new name is the new command. Rewrite the description so it starts with the main use case, then replace the body with your prompt.
   2. Manual only. For a skill with side effects, such as deploying or sending a message, add disable-model-invocation: true to the header. You still run it with /name, but Claude can’t start it on its own.
   3. Supporting files. Keep SKILL.md short, well under 500 lines. Move long examples, templates and reference notes into files next to it, and link each one from SKILL.md, the way client-update links example.md.

   Note: You will see allowed-tools in other people’s skills. It lets Claude use the listed tools without asking, during the turn the skill runs in. It doesn’t limit Claude to those tools. Because it skips permission prompts, read it before you run a skill you didn’t write.

   For “Everyone on this project”

   Commit the skill so everyone who clones the project gets it with the code:

   Terminal or PowerShellCopy

   git add .claude/skills
   git commit -m "Add client-update skill"

   For “Just me, in every project”

   A personal skill lives in your home folder, so git never sees it. To share it later, copy its folder into a project’s .claude/skills/ and commit it there.

   Check it worked

   • Project skill: git log --oneline -1 shows Add client-update skill, and /skills still lists client-update.
   • Personal skill: start Claude Code in a different project and run /skills. client-update is listed there too.

   If it didn’t work

   Your new skill doesn’t show up in /skills

   Check that the copy has its own folder with a SKILL.md inside, and that its first line is ---. Then run /reload-skills.

   It worked — finish Not yet Back