Load Claude Code Skills Before You Build Anything

Last updated: September 2026

We are going to set up Claude Code skills on a real project: audit what is loaded now, install what the project actually needs, put it at the right scope, confirm it attached, and check what each skill is permitted to do before you trust it. By the end you will be able to open any repository and answer, in about two minutes, whether Claude Code is working from current best practice or guessing from memory. That question matters more than it sounds, because when the answer is "guessing", nothing tells you.

One of my students spent five sessions building a website. It broke when you zoomed. A scroll effect he asked for repeatedly never landed. In session six we found the cause, and it was not the code: the entire project had been built with no skills and no plugins loaded at all. Claude had been working from memory the whole time. My phrase for it, which he has since repeated back to me, is working in the dark.

In the same month a second student hit the identical problem from the other direction. The skills for her build were meant to be installed before she started and were simply forgotten, so her first scaffold went up without any of that guidance baked into it. Two people, two projects, no connection between them, same invisible fault.

That is what makes this worth fifteen minutes of your time rather than a bookmark. Nothing in either project errored. Nothing warned. The output looked finished, and the only way either of them found out was by comparing it against something built properly. A failure you cannot see is not a failure you will get around to fixing.

What you need before starting

• Claude Code installed and authenticated (install guide)
• A real project directory, ideally one you are mid-way through
• Terminal access and about fifteen minutes
• No prior experience with skills or plugins

Step 1: Find out what is actually loaded

Start with the audit, because most people have never looked. A skill is a SKILL.md file in a specific directory. If those directories are empty, Claude Code has nothing extra to work with, and it will not tell you.

Check both locations from your project root:

# Project skills, then personal skills
ls .claude/skills/*/SKILL.md
ls ~/.claude/skills/*/SKILL.md

If both return "No such file or directory", you have your answer. That is exactly what my student's project returned in session six.

Inside Claude Code there is a faster read. Type /skills for the menu of everything loaded, and /context for what is occupying the context window right now.

Checkpoint: you can state, out loud, how many skills this project has loaded. "None" is a valid and very common answer.

Step 2: Learn what a Claude Code skill actually is

So what are Claude Code skills? A Claude Code skill is a markdown file, named SKILL.md, that holds instructions Claude loads only when your request calls for it. It sits in a .claude/skills/ directory, carries a name and a description in its frontmatter, and extends what Claude knows without you pasting the same guidance into chat every time. That is the whole idea. The rest is where you put it and how you confirm it arrived.

The distinction that makes everything else make sense, and almost nobody gets told it, is this one.

A skill is on demand. Claude Code loads a listing of every skill's name and description at startup so it knows what exists, then pulls the full body of a skill into context only when something in your prompt calls for it. The official documentation puts it plainly: a skill's body loads only when it is used, so long reference material costs almost nothing until you need it.

A CLAUDE.md file is always on. It is added to the conversation every session, whether or not it is relevant.

That single difference tells you where any piece of guidance belongs. Facts your project always needs, like "this is a Next.js 16 codebase and params are Promises", go in CLAUDE.md. A three hundred line accessibility checklist belongs in a skill, where it costs you nothing until the moment Claude is writing markup. If you want the other half of this, I wrote a full piece on what goes in a CLAUDE.md file.

There is a real cost worth knowing about. The startup listing has a character budget that scales at one percent of the model's context window. When you install enough skills to overflow it, Claude Code starts shortening descriptions, beginning with the skills you invoke least. Shortened descriptions can lose the exact keywords Claude needs to match your request, so a skill you installed sits there, loaded, and never fires. More is not better.

The second half of the cost arrives after a skill fires. Once its body is in context it stays there across turns, so every line you wrote is a recurring charge for the rest of the session, not a one-off. This is why a good skill reads like a checklist rather than an essay. State what to do. Skip the explanation of why, which is the part you wrote for yourself and the model does not need.

Long sessions have one more wrinkle worth knowing before it surprises you. When the conversation is summarised to free up context, Claude Code re-attaches the most recent invocation of each skill after the summary, keeping the first 5,000 tokens of each within a combined budget of 25,000. It fills that budget starting from the most recently used skill. If you have invoked a lot of skills in one long session, the older ones can drop out entirely, which is a perfectly good reason to start a fresh session for a new piece of work rather than running one session all day.

Checkpoint: you can explain, in one sentence, why a long reference document belongs in a skill and a short project fact belongs in CLAUDE.md.

Step 3: Decide what this project needs

Do not install a pile of skills because a listicle recommended them. Ask Claude to research it, in the project, with the project in front of it. My second student who hit this did exactly that, and it worked better than my own guesses would have.

A prompt along these lines is enough:

Look at this codebase and tell me which Claude Code skills and plugins
would measurably improve your output here. For each one, name what it
gives you that you do not already have, and say what you would do
differently with it loaded. Rank them and argue for the top four.

The reason this beats a generic list is that the answer depends on what you are building. A front-end project wants browser automation so Claude can actually see the rendered page, a current-documentation source so it stops writing last year's API, and design guidance. A data pipeline wants none of those.

Notice what the prompt asks for. Not "which skills are good", which produces a list anyone could have written, but "what would you do differently with it loaded", which forces a specific claim you can check afterwards. That phrasing matters more than the tool names it returns. A model asked to recommend will happily recommend. A model asked to say what changes has to commit to something.

For my student's website the useful set was four: browser automation, a current-documentation server, a front-end design skill, and a language server. That was the whole fix. Four installs, a restart, and one prompt he wrote himself. The site started improving in the same session, after five sessions of not improving.

Checkpoint: you have a written shortlist of three to six candidates with a reason attached to each.

Step 4: Install at the right scope

Skills live in two places, and the difference is not cosmetic.

Personal skills go in ~/.claude/skills/<name>/SKILL.md and apply to every project on your machine. Project skills go in .claude/skills/<name>/SKILL.md and apply to that project only. Project skills load from the directory where you start Claude Code and every parent directory up to the repository root, so starting in a subfolder still picks up skills defined at the root.

Default to project scope. A front-end accessibility skill loaded into your data work is pure cost: it eats listing budget and matches nothing.

For most people the install comes from the official marketplace, which Claude Code adds for you the first time you start it interactively. You only need the first line below if that failed, for example because your network blocked the download:

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official

Running /plugin on its own opens a browser where this gets easier to judge. The detail pane for a plugin shows a context cost estimate in tokens, a last updated date, and a full list of what it will install: commands, skills, agents, hooks, and any MCP or language servers. Read the context cost before you install. It is the number that decides whether a plugin earns its place, and it is sitting right there.

The install also asks for a scope, and here the plugin vocabulary differs from the skill vocabulary in a way that catches people. User scope means you, everywhere. Project scope means everyone on this repository, written into .claude/settings.json. Local scope means you, this repository only. Project scope is the one that commits a decision to your teammates, so pick it deliberately.

Writing one by hand is genuinely small. A skill is frontmatter plus instructions:

mkdir -p .claude/skills/accessibility-pass

---
name: accessibility-pass
description: Accessibility checks for this site. Use when writing or reviewing markup, components, or anything user facing.
---

Before returning markup:
- Every interactive element reachable and operable by keyboard
- Visible focus state on every focusable element
- Contrast at 4.5:1 for body text, 3:1 for large text
- Alt text that describes purpose, not appearance
- Headings in order, no skipped levels

That description field is doing more work than it looks. It is what Claude reads at startup to decide whether the skill is relevant, so write it as trigger conditions, not as a summary. "Accessibility checks" alone will not fire. "Use when writing or reviewing markup, components, or anything user facing" will.

Checkpoint: ls .claude/skills/*/SKILL.md now returns your new skill.

Step 5: Restart, or know why you do not have to

This is where the advice you will read elsewhere is wrong, including advice I was giving earlier this year.

Claude Code watches your skill directories and picks up changes mid-session. Edit a SKILL.md, and the change is live in the current session with no restart. That is live change detection, and it applies strictly to SKILL.md text.

There are three real exceptions, and they are the reason the "just restart" folklore exists:

A top-level skills directory created after the session started is not watched. If you had no .claude/skills/ at all and you just created it, Claude Code has nothing to watch and you must restart. That is the most common case for anyone setting this up for the first time, which is why it looks like a universal rule.

Plugin components other than SKILL.md need a reload. Hooks, MCP configuration, agents, and output styles inside a plugin need /reload-plugins or a restart before they apply, as the plugins reference sets out. Edits to a plugin skill's SKILL.md still take effect immediately. It is only the other components that wait.

Nested skills below your starting directory are not loaded at startup. They attach the first time Claude reads or edits a file inside that subdirectory, and stay available for the rest of the session. Until then they do not appear in autocomplete and cannot be invoked by name, which in a monorepo looks exactly like a broken install.

So the honest rule is narrower and more useful than the folklore: restart when you created the skills directory itself, or when a plugin install tells you to. On that last point you do not have to guess. The install summary says either Plugin is now active. or Run /reload-plugins to activate., and you do what it says. Read the summary instead of reflexively restarting.

One related trap is worth knowing if you work across several repositories. Starting Claude Code with --add-dir loads .claude/skills/ from each added directory automatically, which is an exception to how that flag normally behaves, since it otherwise grants file access rather than configuration. The permissions.additionalDirectories setting in settings.json does not do the same thing. It grants file access only, and loads no skills, commands, or subagents. If you added a directory through settings and expected its skills to come with it, they did not.

Checkpoint: you restarted if you created .claude/skills/ in this session, and you know why you did.

Step 6: Verify they attached

Do not skip this. My student's second session went wrong because installation was assumed rather than confirmed.

Inside Claude Code, /skills lists what is loaded and /context shows what is consuming the window. Your new skill should appear by name. Plugin skills appear with the plugin name prefixed, as plugin-name:skill-name, and you invoke them the same way.

If a skill is missing from /skills, work down this list in order: the file must be named SKILL.md exactly, capitals included, it must sit in its own directory under .claude/skills/ rather than loose in the folder, the frontmatter needs both name and description, and the directory must have existed when the session started. In my experience the first and second account for most of it. People create .claude/skills/accessibility.md and wait for something to happen.

If it is a plugin skill that will not appear, the documented fix is to clear the cache with rm -rf ~/.claude/plugins/cache, restart Claude Code, and reinstall the plugin.

One habit worth building now, because it generalises well beyond this: verify with the tool, not with the model. Asking Claude "did the skill load?" gets you a confident answer assembled from context rather than a reading of the actual loaded set. /skills reads the real thing.

Checkpoint: you can see your skill in /skills by name.

Step 7: Read what the skill is allowed to do

A skill is instructions the model will follow. That is the entire point of it, and it is also the risk. A skill you did not write, from a repository you did not read, is code you are running.

The specific mechanism worth knowing: a skill can declare allowed-tools in its frontmatter, which grants Claude those tools without per-use approval for the turn that invokes it. Workspace trust does not gate this. The documentation is direct about the consequence, warning that a skill can grant itself broad tool access and that you should review the allowed-tools of skills checked into a repository before you run Claude Code there.

One command before you trust a directory of skills someone else wrote:

grep -rn "allowed-tools" .claude/skills/

Read what comes back. A documentation-formatting skill asking for Bash is worth a question. The grant is scoped to the turn that invoked the skill and clears when you send your next message, which limits the blast radius but does not remove it.

The scenario to keep in mind is not someone attacking you personally. It is cloning a repository to try something, running Claude Code in it, and inheriting whatever the project's .claude/skills/ directory says. You would read a Makefile before running make. This is the same category of thing, and almost nobody treats it that way yet.

Practical policy, and it is the one I teach: prefer the official marketplace, have Claude research reputable options rather than picking blind, treat stars on a repository as a rough credibility signal and nothing stronger, and read the frontmatter of anything that arrives with a project you cloned.

Checkpoint: you have read the allowed-tools of every skill now loaded, or confirmed none declare any.

Where this breaks

You install skills and nothing changes, because the descriptions do not match your prompts. This is the most common quiet failure. The startup listing is name and description only, so a skill whose description reads like a title never fires. Rewrite descriptions as trigger conditions: when should Claude reach for this? If you have installed more than a dozen, expect the listing budget to start truncating the ones you rarely use.

You install globally and wonder why context fills up. Personal skills follow you into every project. Loaded skill bodies stay in context across turns once invoked, so every line is a recurring cost for the rest of the session. Keep project-specific guidance at project scope.

A personal skill silently shadows a project one. Precedence runs enterprise over personal over project. If you have a deploy skill in both ~/.claude/skills/ and your project, /deploy runs the personal one. This produces genuinely confusing behaviour on a team, where your machine does something nobody else's does.

You verify by asking Claude whether the skill loaded. It will tell you something agreeable. Check /skills, which reads the actual loaded set. This is the same class of mistake as trusting a model's account of its own configuration, and it is worth breaking the habit early.

You write the description as a title instead of a trigger. This is worth stating twice because it is the difference between a skill that works and a skill that sits there. description: Accessibility helper tells Claude nothing about when to reach for it. Name the situations: the file types, the tasks, the words a person would actually use. You are writing matching conditions, not a label.

The output looks fine, so you assume it is fine. This is the failure that cost my student five sessions, and it is the reason this article exists. Nothing errored. The site rendered. It was quietly worse than it should have been, and the only way anyone noticed was comparing it against something built properly.

What to build next

The obvious next move is to make this measurable rather than theoretical. I am running exactly that experiment at the moment: three bots, each managing one thousand dollars of simulated money against live prices, with no real money and no brokerage anywhere in the project. It is built to be filmed, it is unfinished, and I am making no claims about returns because there are none to make. What makes it useful here is the roster. One bot runs on Claude Opus 5 with no skills. A second runs the same model, same prompt, same everything, with a skills directory. A third runs a cheaper model with no skills. The only difference between the first two is one directory.

Adversarial review of that setup found something honest and worth repeating: the control bot can read the skills directory anyway, because file reads are unscoped from the project root. A controlled comparison is harder to build than it looks, which is exactly why so few of the confident claims you read about AI tooling are worth much.

You can run a smaller version today. Take a task you have already completed, start a fresh session with skills loaded, run the same prompt, and compare the two outputs side by side. That comparison is the whole lesson. My second student did the equivalent after installing eight skills at project scope, and the first performance and accessibility trace found two real bugs and scored accessibility at 93 rather than 100. Those bugs had been there for days.

From there, the natural extensions are a handoff file so a future session can recover your setup, and putting this to work on something real, like building a portfolio site with Claude Code.

This changed what I teach. Installing skills, restarting when it is actually required, and verifying they attached is now part of the track rather than something I assumed people had done. If you want to build this with someone watching your screen and catching mistakes in real time, that is literally what my sessions are. Book a free Discovery Call and bring this project to it.

These tutorials come from the actual curriculum I teach 1-on-1. Every code block is tested before it ships.