#claudecode #ai #tutorial #blog #blogpost #development #automation #skills

How to Create Skills in Claude Code — A Technical Tutorial

Claude Code skills are custom slash commands that extend Claude’s capabilities with your own playbooks, checklists, and procedures. Instead of repeating the same instructions every session, you write them once as a skill and invoke them with /my-skill whenever you need them.

This tutorial covers two complete examples: finding and using a ready-made skill, and building your own from scratch.

---

What Are Skills?

Skills are prompt templates stored as Markdown files with YAML frontmatter. When you type /skill-name, Claude loads the instructions from that skill file and follows them for the rest of the session.

They are not code. They are not plugins. They are structured instructions that tell Claude how to approach a specific task — with the right context, the right tools, and the right constraints.

Built-in skills ship with Claude Code:

• /simplify — review changed code for quality and efficiency
• /commit — stage and commit with a well-crafted message
• /review-pr — review a pull request
• /loop — run a command on a recurring interval
• /schedule — create scheduled remote agents
• /claude-api — build apps with the Anthropic SDK

Type / in the Claude Code prompt to see all available skills.

---

How Skills Are Stored

Every skill is a directory containing at minimum a SKILL.md file:

my-skill/
├── SKILL.md              # Main instructions (required)
├── template.md           # Optional supporting files
├── examples/
│   └── sample-output.md  # Example output for Claude to follow
└── scripts/
    └── validate.sh       # Scripts Claude can execute

Skills live in one of two locations:

Location	Path	Scope
Personal	~/.claude/skills/my-skill/SKILL.md	Available in all your projects
Project	.claude/skills/my-skill/SKILL.md	Available in this project only

Claude Code watches these directories for changes — adding or editing a skill takes effect immediately without restarting.

---

The SKILL.md File Structure

Every skill file has two parts: YAML frontmatter (configuration) and Markdown content (the actual instructions Claude follows).

---
name: my-skill
description: What this skill does and when to use it
---

# Instructions for Claude

Your detailed instructions go here in Markdown.
Claude follows these instructions when the skill is invoked.

Frontmatter Fields Reference

Field	Type	Description
name	string	The slash command name. Lowercase, hyphens, max 64 chars. If omitted, uses the directory name
description	string	When to use this skill. Claude uses this to decide relevance. Always include this
when_to_use	string	Additional trigger phrases and example requests
argument-hint	string	Hint shown in autocomplete, e.g. [filename] [format]
arguments	list	Named positional arguments for $name substitution
disable-model-invocation	boolean	If true, only you can invoke it (Claude won’t auto-trigger). Use for dangerous operations like deploy
user-invocable	boolean	If false, hidden from / menu. Only Claude can invoke it (background knowledge)
allowed-tools	list	Tools Claude can use without asking permission
model	string	Override the model while this skill is active
effort	string	Override effort level: low, medium, high, max
context	string	Set to fork to run in an isolated subagent context
agent	string	Subagent type when context: fork is set (e.g. Explore, Plan)

Argument Placeholders

Skills can accept arguments when invoked:

Placeholder	Description
$ARGUMENTS	All arguments as a single string
$0, $1, $2…	Positional arguments (zero-indexed)
$name	Named argument (declared in arguments frontmatter)
${CLAUDE_SKILL_DIR}	Path to the skill’s directory

Multi-word arguments use quotes: /my-skill "hello world" second → $0 = “hello world”, $1 = “second”.

---

Example 1 — Using a Ready-Made Skill

Let’s use the built-in /simplify skill as an example. After writing code, you invoke it:

/simplify

Claude reads your recent changes, reviews the code for reuse opportunities, quality issues, and efficiency problems, then fixes what it finds. You didn’t write any instructions — the skill came pre-packaged.

Finding More Skills

Community skills can be found on GitHub and copied into your skills directory:

# Clone someone's skill into your personal skills
mkdir -p ~/.claude/skills
cd ~/.claude/skills
git clone https://github.com/someone/claude-skill-review-code review-code

Or simply create the directory and paste the SKILL.md content:

mkdir -p ~/.claude/skills/review-code

Then create ~/.claude/skills/review-code/SKILL.md with the skill content.

Using a Skill With Arguments

Many skills accept arguments. For example, if a skill is designed to review a specific file:

/review-code src/auth/login.ts

Claude receives the argument and knows which file to focus on.

---

Example 2 — Building Your Own Skill: /blog-post

Let’s build a complete custom skill that transforms rough notes into polished blog posts — perfect for turning iA Writer notes into Medium articles.

Step 1 — Create the Directory

mkdir -p ~/.claude/skills/blog-post

Step 2 — Create SKILL.md

Create the file ~/.claude/skills/blog-post/SKILL.md:

---
name: blog-post
description: Transform rough notes into a polished blog post. Use when you have a file with scattered ideas, bullet points, or links and want a comprehensive, well-structured article ready for Medium or a personal blog.
when_to_use: "Write blog post, create article, polish notes, expand outline, turn notes into essay"
argument-hint: [filename]
allowed-tools: Read Glob Grep WebFetch
effort: high
---

# Blog Post Writer

Transform the file at $ARGUMENTS into a polished, comprehensive blog post.

## Process

1. **Read the source file** — Understand all the content, links, and ideas
2. **Fetch web links** — Read every URL in the document to gather current information
3. **Identify the narrative** — Find the story thread connecting the ideas
4. **Write the article** — Expand every point into clear, detailed prose

## Writing Rules

- Start with a compelling opening that states the problem or opportunity
- Use `{{TOC}}` after the tags for iA Writer table of contents
- Use `---` horizontal rules between major sections
- Write in British English
- Keep paragraphs short (3-4 sentences maximum)
- Use tables for comparisons and data
- Use code blocks for technical examples
- Include practical, actionable advice — not just theory
- End with a clear conclusion

## Structure

Every blog post must include:
1. Tags at the top (#tag format)
2. A compelling title (# heading)
3. An opening paragraph that hooks the reader
4. Logically organised sections with ## headings
5. Tables, lists, or code where they add clarity
6. A ## Related Notes section with [[wiki-links]] to connected notes
7. A ## References section at the bottom with Harvard-style citations for all web sources

## Tone

Write as a practitioner sharing real experience — not as an academic or a marketer.
Be direct. Be specific. Be opinionated where you have evidence.
Avoid filler words, unnecessary transitions, and hedge language.

## Output

Overwrite the original file with the polished blog post.
Preserve any existing tags and add new relevant ones.

Step 3 — Add a Supporting Template (Optional)

Create ~/.claude/skills/blog-post/template.md for reference:

# Blog Post Template

#tag1 #tag2 #tag3

{{TOC}}

# Title — Subtitle That Adds Context

Opening paragraph. State the problem. Why should the reader care?

---

## Section 1

Content with real depth.

## Section 2

More content. Use tables:

| Column 1 | Column 2 |
|----------|----------|
| Data     | Data     |

---

## Conclusion

What should the reader do next?

---

## Related Notes

- [[Related Note 1]]
- [[Related Note 2]]

---

## References

[1] Author. (Year). 'Title'. *Publication*. Available at: URL (Accessed: Date).

Step 4 — Use It

Now in any Claude Code session, type:

/blog-post "AI in EHR.md"

Claude will:

1. Read the file
2. Fetch all web links in the document
3. Research the topic
4. Rewrite the entire file as a polished blog post
5. Add tags, related notes, and Harvard-style references

---

Example 3 — Building a Healthcare Skill: /clinical-review

Here’s a more advanced skill for reviewing clinical documentation in an EHR project:

mkdir -p .claude/skills/clinical-review

Create .claude/skills/clinical-review/SKILL.md:

---
name: clinical-review
description: Review clinical data models and FHIR resources for accuracy, completeness, and standards compliance. Use when building or modifying healthcare data structures, API endpoints, or clinical forms.
when_to_use: "Review FHIR resource, check clinical model, validate healthcare data, check HL7 compliance"
argument-hint: [file-or-directory]
disable-model-invocation: true
allowed-tools: Read Glob Grep WebFetch
context: fork
agent: Explore
---

# Clinical Data Model Review

Review the healthcare data structures in $ARGUMENTS for clinical accuracy and standards compliance.

## Check against these standards

1. **FHIR R5 compliance** — Do resources follow the official FHIR specification?
2. **SNOMED CT coding** — Are clinical terms mapped to valid SNOMED codes?
3. **ICD-11 diagnoses** — Are diagnosis codes current and correctly applied?
4. **Data completeness** — Are required clinical fields present (identifiers, dates, status)?
5. **Terminology bindings** — Are value sets correctly bound to coded fields?

## Review checklist

- [ ] Patient identifiers follow MPI standards
- [ ] Dates use ISO 8601 format
- [ ] All coded fields have system   code   display
- [ ] Mandatory FHIR elements are not missing
- [ ] Extensions are properly namespaced
- [ ] References between resources are valid

## Output format

For each issue, report:
- **File:line** — location
- **Severity** — Error / Warning / Info
- **Standard** — Which standard is violated
- **Current** — What the code currently does
- **Expected** — What it should do
- **Fix** — Specific change needed

Summarise findings at the end with counts by severity.

Usage:

/clinical-review src/fhir/resources/

This runs in a forked Explore context, reads all the FHIR resource files, checks them against standards, and reports issues — without modifying any files.

---

Advanced Techniques

Dynamic Context with Shell Injection

Fetch live data before Claude sees the instructions:

---
name: pr-review
description: Review the current pull request
allowed-tools: Bash(gh *)
---

## Current PR context

- **Diff:** !`gh pr diff`
- **Comments:** !`gh pr view --comments`
- **Changed files:** !`gh pr diff --name-only`

Review the changes above for bugs, performance issues, and security concerns.

The !`command` syntax executes the shell command and injects the output into the prompt before Claude processes it.

Controlling Who Can Invoke

Scenario	Frontmatter	You invoke	Claude auto-invokes
Normal skill	(default)	Yes	Yes
Manual only (deploy, delete)	disable-model-invocation: true	Yes	No
Background knowledge	user-invocable: false	No	Yes

Using Supporting Files

Keep SKILL.md under 500 lines. Move detailed references to supporting files that Claude loads on demand:

---
name: api-design
description: Design APIs following our conventions
---

Follow our API design standards.

For endpoint naming conventions, see [naming.md](naming.md).
For error response format, see [errors.md](errors.md).
For authentication patterns, see [auth.md](auth.md).

Claude reads the supporting files only when it needs them, keeping the initial context lean.

Granting Tool Permissions

Avoid repeated permission prompts by pre-authorising tools:

---
name: git-cleanup
description: Clean up git branches and stale refs
allowed-tools: Bash(git branch *) Bash(git remote *) Bash(git fetch *)
---

Use glob patterns: Bash(git *) allows all git commands. Bash(npm test *) allows test commands only.

---

Best Practices

1. Write specific descriptions — “Review React components for accessibility violations” is better than “Review code”

2. Use disable-model-invocation: true for destructive operations — deploy, delete, reset, push. Don’t let Claude decide to deploy on its own

3. Start simple, iterate — Begin with a 10-line SKILL.md. Add complexity only when you need it

4. Store personal skills in ~/.claude/skills/ — They follow you across every project

5. Store project skills in .claude/skills/ — Share them with your team via git

6. Use argument-hint — It makes autocomplete much more helpful: argument-hint: [filename] [output-format]

7. Test with /skill-name --help — Claude will explain what the skill does before running it

8. Keep SKILL.md focused — One skill, one job. Don’t combine “deploy AND test AND lint” into one skill

---

Quick Start Checklist

# 1. Create the skill directory
mkdir -p ~/.claude/skills/my-skill

# 2. Create SKILL.md
cat > ~/.claude/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: What it does and when to use it
argument-hint: [arguments]
allowed-tools: Read Glob Grep
---

# My Skill Instructions

When invoked, do the following with $ARGUMENTS:

1. Step one
2. Step two
3. Step three
EOF

# 3. Use it immediately (no restart needed)
# In Claude Code, type: /my-skill some-argument

That’s it. Three files, five minutes, and you have a reusable skill that works in every session.

---

Related Notes

• Claude Code AI Resources for EHR Development
• Blog Post Index
• Workflow Automation Platforms
• 16 Core Components of Modern Apps
• How to Automate Your Life

---

References

[1] Anthropic. (2026). ‘Claude Code Documentation — Custom Skills’. Anthropic Docs. Available at: https://docs.anthropic.com/en/docs/claude-code (Accessed: 23 April 2026).

[2] Anthropic. (2026). ‘Claude Code Skills Specification’. Anthropic. Available at: https://docs.anthropic.com/en/docs/claude-code/skills (Accessed: 23 April 2026).