How to preserve recurring instructions, local rules, and workflow knowledge.
Every session with Claude Code begins from zero. It will not remember your citation style, your metadata schema, or your local workflow rules unless you give that knowledge some more durable form. A skill stores those instructions in a file that Claude Code can load when the task matches, so you write them once and they persist across sessions.
A skill works like a reference sheet pinned to the wall of your office, except Claude Code checks it automatically. You keep it updated as your rules evolve, and every session benefits from whatever you have added so far.
A skill is a folder containing a markdown file called SKILL.md. The file has two parts. The first is a YAML frontmatter header, the small structured block between --- delimiters that tells Claude Code when to use the skill. The second is a body that contains the instructions themselves.
A skill can also include reference documents, templates, and sample data alongside the main file, as covered below in How to Build a Skill.
Any instruction you find yourself repeating across sessions is a candidate.
Teach Claude Code the rules of a specific standard, format, or system. Citation styles, metadata schemas, cataloging rules, naming conventions.
Capture a multi-step process you repeat. Processing interlibrary loan requests, preparing data for a specific platform, generating reports in a particular format.
Define how to check that output is correct. What to validate in a metadata record, how to spot-check a data transformation, what a properly formatted export looks like.
Specify how results should be formatted and delivered. Your institution's report template, a specific CSV structure for import into another system, an exhibit metadata format.
Your institution's metadata profile: which fields are required, what controlled vocabularies to use, how to format dates. Once encoded in a skill, Claude Code follows the local rules when creating or cleaning records without being reminded each time.
The exact structure a target system expects for imports: column names, field order, date format, encoding. Particularly useful when the import format is finicky or underdocumented.
Inclusion/exclusion criteria for a systematic review, covering population definitions, outcome measures, study design requirements, and sub-topic categories. Consistent application across hundreds of records is exactly the kind of repetitive judgment call that benefits from written-down rules.
How to query a specific API (OpenAlex, OCLC WorldCat, your institution's repository), including endpoints, authentication, and pagination. Without reference docs, Claude Code tends to guess at parameter names and get them wrong.
Claude Code includes a built-in skill creator. Describe the task and the recurring failure points, and it will build an initial structure for you.
Claude Code generates the file structure and the initial text.
Type /skill-creator in Claude Code and describe the skill you want. Claude Code will ask a few questions, then generate the folder, the SKILL.md file, and any supporting files.
"I want a skill that formats metadata for our institutional repository. We use a modified Dublin Core profile. Required fields are title, creator, date (YYYY-MM-DD), type, and rights. The rights field should always be set to our standard license statement unless I specify otherwise. Creator names should be in 'Last, First' format. I'll give you our controlled vocabulary for the type field."
Claude Code will generate the skill and walk you through reviewing it, after which you should test it on a task to see where the instructions hold up and where they need refinement.
If you would rather build a skill yourself, or if you want to understand the mechanics, the process is straightforward:
~/.claude/skills/ (the ~ means your home directory) with a hyphenated name (e.g., dublin-core-metadata)SKILL.md file inside it with the header (name and description) and the body (your instructions)references/ or assets//your-skill-name in Claude Code and trying it on a taskThe folder can also hold reference documents, templates, and sample data beyond the SKILL.md file itself. Keep the main file concise and move detail into side files; Claude reads the extra material when it needs it.
Use ~/.claude/skills/ for personal defaults you want available everywhere. Use .claude/skills/ inside a project when the instructions belong to that project or need to be shared with other people.
When you write a skill, you have to make sure it activates when needed and captures the local rules Claude would otherwise have to guess at. When format matters, an example of correct output also helps.
Claude Code reads each skill description at the start of a session and loads any that seem relevant to the task at hand. A clear description makes this automatic activation more reliable. You can also invoke a skill directly by typing /skill-name, which always works regardless of how the description is written, but automatic activation saves you from having to remember to invoke it.
Claude Code already knows general background about most standards and file formats. The skill should focus on the local rules and edge cases Claude would otherwise have to guess at.
You do not need to explain what Dublin Core is or how CSV files work. Claude Code already knows that much. What it does not know is that your institution requires the dc.rights field to contain a specific license URL, or that your date field must use EDTF (Extended Date/Time Format) notation for uncertain dates. Focus the skill on those local demands.
Add a list of mistakes Claude Code tends to make. Each time you see a repeated error while using the skill, add it to the gotchas.
Rules tell Claude Code the constraints. Examples show what a correct result looks like. When format matters, examples are usually more useful than abstract rules. Give Claude Code the boundaries and the local rules, and let it work out the mechanics. Skills that script every step are brittle. They fail on tasks that differ even slightly from the one you wrote them for.
First versions are usually short. You improve a skill by using it, noticing where Claude Code goes wrong, and adding what was missing.
Tell Claude Code: "I want to create a skill called [your-name-here]. Here's what it should know: [paste in the instructions you keep repeating]. Use /skill-creator to set it up."
A metadata skill might start with just the required fields and date format. After a few uses, you have a gotchas list. Creator names with suffixes get inverted incorrectly, the rights field needs a particular URL, multi-value fields are separated with pipes. You only discover those details by using the skill.
The most common failure is that a skill never activates automatically because the description does not match how you phrase your requests. Try adding trigger phrases that reflect your natural wording, or invoke the skill explicitly with /skill-name to confirm the file itself is valid.
When a skill activates but produces wrong output, the instructions are usually ambiguous or missing a case. Add a new gotcha with an example of the correct result. If two skills have overlapping descriptions, both may load at once. To fix this, narrow each description so they trigger in distinct situations. If a skill stopped working after it had worked before, test it with a simple case to see whether the folder structure changed or a Claude Code update shifted behavior.
Once a skill works, you can share it the same way you share any other project asset.
~/.claude/skills/ directory, and it works..claude/skills/ inside a Git repository. Anyone who clones the repo gets the skill automatically.For most teams, a shared Git repository is enough. Updates are tracked through version control, and new team members inherit the same conventions when they clone the project. (If Git is new to you, the Git guide in this series covers the basics.)
Because a skill file is plain markdown, it is readable by both humans and Claude Code. Metadata standards, workflow conventions, and formatting rules encoded as skills can double as onboarding documentation for new team members.
To see how these pieces fit together, here is a complete skill for a common library task: preparing metadata for a digital exhibit in Omeka S.
The skill is short on purpose. It has the field mapping, the date conventions, the rights statement, and a gotchas list. You add to the list as you find more edge cases. There is no need to write a comprehensive version up front.