You will create one instruction file and a small practice workspace. The example needs no API integration or custom agent framework. Claude Code access and sign-in are separate from installing its command-line application.
1. Understand what a skill adds
An Agent Skill is a folder containing a SKILL.md file, with optional scripts, references, and assets. Its name and description help a supporting agent decide when the workflow is relevant; its body explains how to perform the task. This packages a procedure rather than training a new model.
A good first skill solves a repeated problem with a recognizable output: map a repository, review an import file, or prepare a release checklist. A one-off request can stay a prompt. A connection to a CRM or another external system may need a tool or MCP server as well as instructions.
This walkthrough targets Claude Code on your computer. Claude web, the API, and other skill-compatible clients have their own setup, file access, and availability. A folder format does not make every tool or dependency available in every client.
2. Install and check Claude Code
Choose the installation command for your operating system. On Windows, use PowerShell with WinGet available. The macOS/Linux command below uses Anthropic’s native installer. Installing the CLI does not include a paid account, API credit, or permission to read a project.
winget install --id Anthropic.ClaudeCode --exactcurl -fsSL https://claude.ai/install.sh | bashOpen a new terminal after installation so the updated PATH is available, then check the executable. If it is not found, resolve installation/PATH first; creating a skill will not repair a missing CLI.
claude --version3. Create a practice workspace
Run one of these blocks from a directory where you keep projects. Use a new folder named claude-skills-demo; if that folder already contains work, choose a different name. The small README deliberately contains no application code, so you can check whether the assistant admits that limitation.
New-Item -ItemType Directory -Path claude-skills-demo
Set-Location claude-skills-demo
New-Item -ItemType Directory -Force -Path .claude\skills\repo-map
Set-Content -Path README.md -Value '# Demo workspace: no application code has been added yet.'mkdir claude-skills-demo
cd claude-skills-demo
mkdir -p .claude/skills/repo-map
cat > README.md <<'EOF'
# Demo workspace: no application code has been added yet.
EOFCreate .claude/skills/repo-map/SKILL.md in a text editor. On Windows, check that the filename is not accidentally SKILL.md.txt. This project-level folder makes the skill part of this workspace. Keep instructions free of passwords and private keys.
4. Write the complete SKILL.md file
Paste the following Markdown into that file and save it. The lowercase name matches the folder. The description names both the task and when to use it, which is more useful than a generic description such as “help with code.”
---
name: repo-map
description: Explain a repository's structure, entry points, and one request or job flow using file evidence. Use when onboarding to an unfamiliar codebase.
---
# Repository map
1. Start with README and tracked project manifests. Identify the language,
framework, and documented development commands.
2. Find the application entry points, routes or jobs, data-access layer,
tests, and configuration examples. Do not read credentials or .env files.
3. Trace one requested feature through the relevant files. Cite paths and
function names for each connection.
4. Separate observed facts, hypotheses, and questions. If application code
is missing, say so rather than inventing a framework or database.
5. Return: structure, one flow, relevant tests, and unresolved questions.
Do not install packages, run project scripts, edit files, or access external
services as part of this mapping task. Propose any useful command separately.
The request to avoid edits describes the intended workflow. It is not a replacement for Claude Code’s actual permission settings. Use the permissions appropriate to a read-only review and inspect commands before allowing execution. The example does not grant access to a database or external account.
5. Start Claude Code and try the skill
From the claude-skills-demo directory, start Claude Code. Complete the sign-in flow shown by the application and review the workspace trust prompt for this practice directory.
claudeInside Claude Code, invoke the skill and give it a concrete task. This is an instruction for Claude Code’s input, not a shell command to run in PowerShell or Bash.
/repo-map Explain this workspace and identify whether it contains an application entry point.The correct result for the empty demo is a short inventory of the README and skill files, followed by “no application entry point found” or an equivalent statement. A claim about a running API, database schema, or framework would be unsupported. If the skill is not listed, check the file path and frontmatter, then restart Claude Code in this directory.
6. Evaluate it before using it on real work
On small screens, scroll the table sideways to see every column.
| Input | What to check |
|---|---|
| Empty demo workspace | It reports missing application code without inventing a stack. |
| An application you own | It names real entry points and supports a flow with file/function references. |
| “Change the database schema” | It recognizes that the mapping workflow does not cover implementation. |
| A missing or ambiguous feature | It identifies the gap and asks a focused question instead of guessing. |
Next, copy the skill folder into a project you are allowed to review. Start with a small feature and compare the map against the actual files and tests. Record unclear outputs, improve one instruction, and repeat the same cases. Model output can vary; the skill needs evidence checks rather than a claim that it always works.
When the workflow grows, keep its main instructions readable and move substantial supporting material into referenced files. Version the folder with the project and review changes to bundled scripts or tool requirements before using them.
7. Frequently asked questions
Does creating a skill train Claude on my repository?
No. A skill supplies instructions and supporting material during a task. It is not model training. Separately review what project content your chosen Claude product sends or retains under your account settings.
Can I use the same skill in Claude web and Claude Code?
The Agent Skills format supports reuse, but installation, available tools, file access, and dependencies differ by client. The project-level folder and slash-command example in this guide target Claude Code.
Why does my custom skill not appear?
Check that the path is .claude/skills/repo-map/SKILL.md, the file is Markdown rather than a hidden .txt file, and the YAML name and description are present. Start a new Claude Code session from that project directory and inspect any parsing errors.