Claude Code skills: 5 points from the docs and 3 prompts to copy

The documentation puts it simply: create a SKILL.md file with instructions, and Claude adds it to its toolbox. The file starts with a two-line header, the name and the description. Then comes the body: the procedure Claude follows when the skill runs. Next to it, in the same folder, support files: references, examples, scripts.

Create a skill when a section of your CLAUDE.md file has become a full procedure, or when the same instruction keeps coming back from one project to the next. A detail that matters for an SME: Claude Code skills follow the Agent Skills open standard (agentskills.io), adopted by other AI tools. The same folder we write for Claude Code, we hand to the Hermes agents we operate for our clients. Claude Code adds a few fields of its own, such as the locks in point 5; the rest travels as is.

Claude does not read all your skills on every message. The documentation describes progressive disclosure in three levels. At startup, only each skill’s metadata is loaded, about a hundred tokens per skill. The body of the file is read only when the skill triggers. Support files are opened only on demand.

So everything rests on the description. A good description says what the skill does and when to use it, with the words someone would actually use. It is written in the third person, because it is injected into the system prompt. And no vague names: the documentation lists “helper”, “utils” and “tools” as names to avoid. For our LinkedIn carousel skill: create carousels from a topic, a transcript or an outline; use whenever someone asks for a carousel, carousel slides or a LinkedIn post. Our clients’ exact words, not ours.

The documentation lists seven locations. The four to know: a personal skill lives in your user folder and follows you across projects; a project skill lives in the repository, in the .claude/skills folder, and travels with the code, the whole team gets it by cloning; a plugin skill arrives with an installed plugin; an enterprise skill is deployed by the administrator on every machine. The other three cover monorepo subfolders, directories added at launch and skills enabled in a claude.ai account.

When two skills share a name, priority goes to enterprise, then personal, then project. A personal or project skill that is added or edited is picked up in the current session, without restarting; a skill shipped by a plugin requires reloading plugins. Our house rule: everything about a client lives in that client’s project. The skill travels with the repository, and nobody depends on one particular machine.

Conciseness first. The documentation reminds you that Claude is already smart: a skill does not explain what Claude can already do, it adds what Claude cannot guess, in under 500 lines. Then degrees of freedom: for a fragile operation, a narrow bridge with precise steps; for a judgement task, an open field with principles.

Scripts: when a step is deterministic, put it in a script Claude runs. The code executes outside the context, and errors are solved by the script rather than delegated to the model. Feedback loops: a reliable skill produces something you can check, then corrects. For this video, the loop is a contact sheet of frames extracted from the render, reviewed before every delivery.

Evaluations before writing: three real scenarios, run with and without the skill, on several models if possible. And the two-instance method: Claude A helps you write and refine the skill, Claude B uses it on real work, and you report back to A what B missed.

By default, both you and Claude can run any skill. The documentation offers two locks. The first, disable-model-invocation, reserves a skill for you alone: deployment, sending a message, publishing. You do not want Claude to decide to publish because the content looks ready to it. The second, user-invocable set to false, does the opposite: background knowledge Claude loads on its own, but which makes no sense as a command.

A third setting, allowed-tools, pre-approves specific tools for the turn in which the skill runs, and no more. A skill can also run in an isolated subagent, to keep the main conversation clean. And a security reminder from the documentation: installing a skill is installing software. Read what it contains before adding it.

Run it in a project that already has several skills. Claude rereads each description, spots overlaps and rewrites only what is ambiguous. The prompt, to copy as is:

Reread the descriptions of all my skills. For each one, tell me what the skill does, when it should trigger, and where it overlaps with another skill. Rewrite only the ambiguous descriptions, in the third person, with the words a user would use.

Run it right after a successful piece of work, in the same conversation, while Claude still has the whole context: the rules given along the way and the files that were used. The prompt:

Create a skill that captures how we just did this work: the step-by-step process, the rules I gave you along the way, and the useful reference files. Stay concise, Claude already knows the rest. Then rerun the same task with this skill and compare the two results.

Run it when a skill produced a bad result. The idea comes from Anthropic’s engineering article: ask Claude to reflect on what went wrong before fixing, so the skill improves and not only the output. The prompt:

The skill failed on this task. Before fixing the result, reread your trajectory: which file you read, which rule you skipped, what was missing. Propose the smallest change to the skill that avoids this failure, apply it, then replay the task.

Anthropic, Skills in Claude Code: https://code.claude.com/docs/en/skills. Anthropic, Agent Skills overview: https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview. Anthropic, Skill authoring best practices: https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices.

Anthropic Engineering, Equipping agents for the real world with Agent Skills: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills. Every claim in this guide can be found in one of these pages; the examples and the per-client storage rule come from Adygital practice.