Claude Code Skills

A skill is a reusable instruction set stored as a markdown file in your workspace. Where a one-off prompt exists only in the current conversation and disappears when it ends, a skill persists -- versioned, shareable, and invocable by a slash command whenever you need it. The instruction set is just markdown: steps, references to supporting files, and optional YAML frontmatter that controls how Claude Code loads and runs it.

Skill anatomy

A skill lives at .claude/skills/[skill-name]/SKILL.md. Supporting files -- profiles, templates, rubrics, examples -- sit in the same folder and are referenced from the SKILL.md steps. Claude reads the folder when the skill is invoked, giving it access to all the supporting context without loading it unnecessarily in other sessions.

# SKILL.md — writing-linkedin-posts

## Trigger
/linkedin

## Description
Write LinkedIn posts in Larry's voice on any topic. Use when asked
to "write a LinkedIn post", "draft a post about...", or "create a post".

## When to Use
- User asks to write a LinkedIn post
- User says "draft a post about..."

## Steps
1. Read the master profile at Documentation/LARRY_MAGUIRE_MASTER_PROFILE.md
2. Identify topic and target audience from user's prompt
3. Draft a post following the 7-part structure in the profile
4. Apply tone rules: direct, evidence-based, no sycophancy
5. Present for review — offer one revision pass

## Output
A single LinkedIn post, 150–300 words, ready to publish.

## References
- Documentation/LARRY_MAGUIRE_MASTER_PROFILE.md

YAML frontmatter -- full field reference

Add a YAML block at the top of SKILL.md to control exactly how Claude Code loads and runs the skill. All fields are optional.

---
name: writing-linkedin-posts
description: Write LinkedIn posts in Larry's voice on any topic
argument-hint: "[topic or brief]"
allowed-tools: Read, Write, WebSearch
disable-model-invocation: false
user-invocable: true
model: claude-opus-4-6
context: fork
agent: general-purpose
---

What each field means in plain English

YAML fields look technical, but each one answers a simple question about how your skill should behave.

String substitutions

Inside SKILL.md content, Claude Code replaces these variables at invocation time:

# Available substitutions
$ARGUMENTS          — everything the user typed after /skill-name
$0                  — same as $ARGUMENTS
$1, $2, $3          — space-delimited argument tokens
${CLAUDE_SESSION_ID}  — current session ID
${CLAUDE_SKILL_DIR}   — absolute path to the skill's folder

Example use -- a skill that takes a GitHub issue number:

---
argument-hint: "[issue-number]"
---
# fix-issue

Fetch issue #$ARGUMENTS from GitHub and implement the fix.

The user types /fix-issue 247 and $ARGUMENTS becomes 247.

Running in a forked subagent

Heavy skills -- those that read many files, run long research loops, or process batches -- should run in a forked context to protect the main conversation's context budget:

---
context: fork
agent: general-purpose
allowed-tools: Read, Write, Glob, Grep, WebSearch
---
# processing-pdfs

Process all PDFs in the folder passed as $ARGUMENTS.
Write a summary markdown file for each PDF alongside the original.
Return only the list of output files — not the full content.

With context: fork, the skill runs in its own context window. The main conversation receives only the skill's final return value -- not everything the skill read or processed.

Creating your first skill

You do not need to be a developer to write a skill. If you can write a numbered list of instructions, you can write a skill. Here is the process for a non-technical user:

1. Identify the task. Pick something you have explained to Claude at least twice in separate sessions. Meeting summaries, client email drafts, and weekly reports are common first skills.
2. Create the folder. In your workspace, navigate to .claude/skills/ and create a subfolder with the skill name -- for example, meeting-summary.
3. Create SKILL.md. Inside that folder, create a file called SKILL.md. You can ask Claude to help: "Create a skill file for summarising meeting notes" and it will write the file for you.
4. Test it. In a new session, type /meeting-summary. Claude reads the file and runs the process. If it doesn't behave as expected, edit the steps and try again.

The most effective skills are written from memory: think about how you would explain the task to a capable new assistant on their first day, and write that down. Specificity matters more than length -- "write a 200-word summary with three bullet points for action items" produces better results than "write a summary".

Discovery and invocation

Skills in .claude/skills/ are auto-discovered at startup. Claude can invoke them based on the description field -- if the user's request matches a skill's description, Claude may auto-trigger it. Explicit invocation always works: type /skill-name and Claude loads and executes SKILL.md immediately, regardless of context.

Built-in skills

Claude Code ships with bundled skills accessible via slash commands:

• /simplify -- review changed code for reuse, quality, and efficiency
• /debug -- structured debugging with hypothesis-test-eliminate methodology
• /batch -- run a task across multiple inputs in parallel using agents
• /loop -- run a skill on a recurring interval (e.g. /loop 5m /debug)
• /claude-api -- scaffolding and guidance for Anthropic API integrations

Custom skills take the same slash-command form. Do not shadow built-in names -- check /help for the reserved list.

Maintaining skills over time

A skill is a living document. As your process changes, the skill should change with it. Treat SKILL.md files the way you treat any work template: review them when the output isn't meeting expectations, update them when your process improves, and retire them when the task is no longer recurring.

• Versioning. Because skill files live inside your workspace, they are version-controlled automatically if you use git. You can see exactly what changed and when, and revert to an earlier version if an update made things worse.
• Sharing. Skill folders can be copied between workspaces or shared with teammates. A skill that processes your standard invoice format will work equally well in a colleague's workspace, provided they have the same supporting files.
• Updating. Edit SKILL.md directly in a text editor, or ask Claude: "Update the /proposal skill to add a pricing section after the scope section." Claude will edit the file for you and confirm what changed.

Troubleshooting

My skill isn't triggering when I type /skill-name

Check that the SKILL.md file is in the correct location: .claude/skills/[skill-name]/SKILL.md. The subfolder name must match the command name you're typing. If the file exists but the skill still doesn't load, restart Claude Code -- skill discovery happens at startup.

Claude ignores some of my skill instructions

Long skill files with vague steps produce inconsistent results. Audit the Steps section: each step should be a specific action with a concrete output, not a goal. Replace "write a good summary" with "write a 150-word summary with a Key Decisions section (bulleted) and an Action Items section (table with Owner and Deadline columns)". Specificity is the primary lever for reliable skill execution.

The skill runs but produces the wrong format

Add or strengthen the Output section. Specify format (markdown, Word document, plain text), length (word count or section count), and file location if the result should be saved to disk. Claude defaults to in-conversation output unless told otherwise.