Skip to main content
    Kriv AI

    Claude adoption

    Claude skills tutorial: how to build and use your first skill

    A skill is a folder of instructions Claude loads when a task calls for it. This tutorial follows Anthropic's documentation step by step and says where its pages disagree.

    This Claude skills tutorial starts with one fact: a skill is a folder with a SKILL.md file, and Claude uses it when your request matches the skill's description. Anthropic's Claude Code documentation says "Skills extend what Claude can do. Create a `SKILL.md` file with instructions, and Claude adds it to its toolkit. Claude uses skills when relevant, or you can invoke one directly with `/skill-name`." The steps below create a first skill in Claude Code, add one in the Claude app, and test the Claude Code skill. Source: Anthropic, Extend Claude with skills, read 17 November 2026.

    plain answer

    A skill is a folder that holds a SKILL.md file

    Anthropic's overview says "Skills are reusable, filesystem-based resources that give Claude domain-specific expertise." It separates skills from prompts: "Unlike prompts (conversation-level instructions for one-off tasks), Skills load on demand, so you don't have to repeat the same guidance across conversations."

    The folder can hold more than the one file. Anthropic's Claude Code page says "Skills can include multiple files in their directory. This keeps `SKILL.md` focused on the essentials while letting Claude access detailed reference material only when needed." Anthropic's overview describes a skill as a directory containing instructions, executable code and reference materials.

    Anthropic's pages do not agree on a label: its Help Center calls skills in Claude Code and the API beta, while its documentation pages show no label, so check the page for your product.

    plain answer

    Claude picks a skill by reading its description

    Each skill has a short description, and that is what Claude matches your request against. Anthropic's overview says "The `description` is what Claude matches your request against when determining whether to trigger the Skill, so it must say both what the Skill does and when to use it."

    Only the name and description are always loaded. Anthropic says "until a Skill is triggered, only its name and description occupy context." The body of SKILL.md is read when a request matches, and other files in the folder are read only when the instructions point to them. Anthropic calls this progressive disclosure.

    plain answer

    How to create your first skill in Claude Code

    Anthropic gives two places for a skill folder. A personal skill goes in `~/.claude/skills/<skill-name>/SKILL.md` and is available across all your projects on that machine. A project skill goes in `.claude/skills/<skill-name>/SKILL.md`, and Anthropic says "Commit it so your team gets it too."

    Step 1: create the folder, for example `mkdir -p ~/.claude/skills/summarize-changes`. Step 2: write a SKILL.md with two parts. Anthropic says: "YAML frontmatter between `---` markers that tells Claude when to use the skill, and markdown content with the instructions Claude follows when the skill runs." Step 3: test it. Ask something that matches the description, such as "What did I change?", or type the skill name as a command, `/summarize-changes`.

    On the fields: Anthropic's Claude Code page says "All fields are optional. Only `description` is recommended so Claude knows when to use the skill." Its general overview says `name` and `description` are required and gives limits for them. The pages differ, so write both fields and keep the name to lowercase letters, numbers and hyphens.

    plain answer

    How to add a skill in the Claude app

    In the Claude app a skill is uploaded, not saved to a folder on your computer. The steps below come from Anthropic's Help Center article "Use skills in Claude", section "Add and use custom skills". Step 1: "Package your skill folder as a ZIP file." Anthropic's article on creating custom skills adds "The ZIP should contain the skill folder as its root (not a subfolder)."

    Step 2: "Navigate to Customize > Skills." Step 3, in the article's words: To add custom skills, click the "+" button, then "+ Create skill." Step 4: Select "Upload a skill." Step 5: "Upload a ZIP file containing your skill folder." The article ends the list with "Your skill will appear in your skills list and can be toggled on or off."

    Anthropic says "Custom skills you upload aren't visible to colleagues until you share them." It also says the feature "requires code execution to be enabled." Plan availability is worded differently on two Anthropic pages (the Help Center lists Free, Pro, Max, Ultra, Team and Enterprise; the Agent Skills overview lists Pro, Max, Ultra, Team and Enterprise for custom skills), so check your own plan and the Customize > Skills screen instead of relying on this page.

    plain answer

    Skills do not carry over between Claude products

    Anthropic says "Custom Skills do not sync across surfaces." A skill uploaded in the Claude app must be uploaded again to the API, and a Claude Code skill is "filesystem-based and separate from both claude.ai and the API." A team that wants the same skill in all three places keeps one source folder and adds it to each.

    Sharing also differs. Anthropic says API skills are shared workspace-wide, while Claude Code skills are personal or project-based and "Can also be shared through Claude Code plugins."

    plain answer

    Write a narrow description and a short SKILL.md

    Anthropic's skill authoring guide says "The `description` field makes Skill discovery possible and should include both what the Skill does and when to use it." It asks for third person: "Always write in third person." Its good example is "Processes Excel files and generates reports" and its examples to avoid are "Helps with documents" and "Processes data".

    On length, Anthropic says "Keep the `SKILL.md` body under 500 lines for optimal performance" and to split content into separate files near that limit. It also recommends testing with real tasks: "Tested with real usage scenarios" is on its checklist, and it suggests building evaluations before writing extensive documentation.

    plain answer

    Read a skill's files before you add it

    A skill can carry scripts as well as text, so Anthropic treats adding one like installing software. Its overview says "Use Skills only from trusted sources: those you created yourself or obtained from Anthropic." For a skill from elsewhere it says to "thoroughly audit it before use" and to review every bundled file for "unexpected network calls, file access patterns, or operations that don't match the Skill's stated purpose."

    Anthropic's Help Center says that for a skill from a less-trusted source, including one shared by a colleague, you should "review it before enabling." For a company, that means someone owns the question of which skills may be added and who checks them. Anthropic's overview points to a separate page, Skills for enterprise, for governance at organization scale. That page's review checklist starts with "Read all Skill directory content." and it says "Never deploy Skills from untrusted sources without a full audit." It also says "Establish separation of duties: Skill authors should not be their own reviewers."

    Straight answers

    Frequently asked questions about Claude skills tutorial: how to build and use your first skill

    What is a Claude skill?

    A skill is a folder with a SKILL.md file of instructions that Claude uses when a request matches the skill's description. Anthropic says "Skills extend what Claude can do." You can also invoke one directly by typing /skill-name in Claude Code.

    Where does a SKILL.md file go in Claude Code?

    Anthropic gives two paths: ~/.claude/skills/<skill-name>/SKILL.md for a personal skill across all your projects on that machine, and .claude/skills/<skill-name>/SKILL.md inside a repository for a project skill.

    Is a skill the same as a prompt?

    No, by Anthropic's account. It says prompts are conversation-level instructions for one-off tasks, while skills load on demand so the same guidance does not have to be repeated in every conversation.

    Does a skill I made in Claude Code work in the Claude app?

    Not automatically. Anthropic says custom skills do not sync across surfaces and that Claude Code skills are separate from both claude.ai and the API. Each place needs the skill added on its own.

    Should I install a skill someone else wrote?

    Anthropic says to use skills only from trusted sources, and to audit any other skill before use, including every bundled script and file. Treat it like installing software.

    Talk to the team that would do the work

    Bring your requirements to a working session with the person who'll actually deliver.

    Book a Discovery Call