How to Install and Use Claude Skills

To use and create Claude Skills, author a directory-scoped SKILL.md file with YAML frontmatter specifying your trigger description under 1,024 characters, save it in ~/.claude/skills/ for global personal access or .claude/skills/ for repository isolation, invoke it via Claude Code CLI commands or semantic prompts, and verify execution output against structured formatting constraints.

What Is a Claude Skill and How Does Claude Code Discover It?

A Claude Skill is a modular package of procedural instructions, domain constraints, and reference files encapsulated inside a dedicated filesystem directory containing a mandatory SKILL.md entrypoint. Claude Code scans these directories at startup to index available capabilities and dynamically binds them when a user request matches the skill's declared purpose.

According to official Anthropic Claude Code documentation, skills structure "procedural workflows, domain constraints, and reusable prompts into directory-based modules that Claude dynamically invokes based on semantic task matching." Claude Code achieves this with a two-phase loading model: during session startup, Claude Code scans skill directories with sub-200ms latency, reading only the skill names and YAML frontmatter descriptions. The full markdown instruction body is deferred until runtime, keeping token overhead minimal until the user initiates a matching task.

Understanding this mechanism is essential for power users. If your skill description is ambiguous or missing, Claude Code cannot evaluate whether the skill fits the current prompt. Conversely, if your instructions are bundled into a monolithic prompt pasted into every session, you exhaust precious context before work begins. Claude Skills solve both problems by turning unstructured prompts into on-demand execution routines. If you are exploring the foundational architecture before building, start with our guide on what agent skills and Claude Skills are, or follow our hands-on walkthrough using a Claude prompt builder to author reusable skills and subagents.

Where Should You Install Personal vs Project Skills in Claude Code?

Claude Code evaluates skills across two distinct directory scopes: global personal skills stored in ~/.claude/skills/ and project-scoped skills stored in .claude/skills/ at the root of a specific git repository. Project skills take precedence whenever directory names or invocation triggers collide.

Deciding between personal and project scope prevents repository pollution. If an instruction describes your individual review habits or tone preferences, committing it to a team repository introduces friction with colleagues. If an instruction codifies a team deployment checklist, storing it solely in your home directory leaves teammates without the guardrail. For a deeper breakdown of storage precedence and path resolution, read our dedicated guide on Claude skills across projects and directory scopes.

How Do You Author and Structure a Production SKILL.md File?

Authoring a production Claude Skill requires creating a kebab-case directory, defining valid YAML 1.2 frontmatter with name and description attributes, and writing explicit Markdown instructions divided into clear procedural sections.

The directory name must use lowercase alphanumeric characters and hyphens, constrained to 64 characters. Inside that directory, create SKILL.md. The YAML frontmatter must strictly comply with the YAML 1.2 Specification. Below is a complete, production-ready example of a pull request review skill:

---
name: pr-review-audit
description: Comprehensive security and architecture audit for git pull requests. Analyzes diffs for authentication boundaries, missing database indexes, unhandled async errors, and breaking API schema changes. Use when reviewing code changes, auditing PRs, or verifying production readiness before merge. Do not use for basic typographical or lint formatting checks.
---

# Pull Request Review Audit

## 1. Trigger Conditions
Execute this workflow when the user requests a pull request review, asks to inspect a branch diff, or runs `/pr-review-audit`.

## 2. Required Inputs
- Git diff between target base branch and feature branch (`git diff main...HEAD`)
- Changed schema definitions or database migration files
- Associated test files modified in the changeset

## 3. Step-by-Step Procedure
1. Inspect Authentication Boundaries: Verify that all newly exposed routes or controllers enforce session or token authentication. Flag any bypassed middleware.
2. Check Database Query Efficiency: Inspect new SQL queries or ORM calls. Flag unindexed foreign key lookups or N+1 query patterns.
3. Validate Error Handling: Ensure asynchronous operations have explicit try/catch blocks or rejected promise propagation.
4. Verify Regression Test Coverage: Confirm that every bug fix or new capability includes a corresponding unit or integration test.

## 4. Output Contract
Produce the final report strictly matching this structure:
### Summary Assessment
[One-sentence approval verdict: APPROVED, CHANGES_REQUESTED, or BLOCKING_SECURITY_RISK]

### Critical Findings (P0/P1)
- [File:Line] Description of vulnerability or regression risk
- [Remediation] Concrete code fix or architectural correction

### Recommendations (P2/P3)
- Non-blocking optimizations or test coverage improvements

Notice the frontmatter description. A Claude Skill description must stay under 1,024 characters while explicitly identifying the task, required inputs, output format, and negative boundaries ("Do not use for basic typographical checks"). This precision prevents Claude Code from hallucinating matches on unrelated requests. For an in-depth reference on frontmatter schema options, read our breakdown in the agent skills and SKILL.md guide.

For complex workflows that require reference rubrics, scripts, or golden dataset templates, do not crowd everything into a single file. You can organize supporting assets into subdirectories within the skill package. Learn how to structure multi-file packages without inflating token costs in our guide to multi-file Claude Skills.

Step-by-Step Installation: How Do You Add Skills to Claude Code?

To install a Claude Skill, copy or move the entire skill directory into either your global personal directory (~/.claude/skills/) or your repository project directory (.claude/skills/).

Installing a Personal Skill on macOS / Linux

Execute the following shell commands in your terminal to create the directory and place the skill file:

# 1. Create the personal skills directory container
mkdir -p ~/.claude/skills/pr-review-audit

# 2. Copy the authoring entrypoint into the container
cp SKILL.md ~/.claude/skills/pr-review-audit/SKILL.md

# 3. If your skill uses external templates or reference rubrics, copy the entire folder
cp -R pr-review-audit/ ~/.claude/skills/pr-review-audit/

Installing a Project Skill in a Git Repository

For repository-specific workflows, install the skill at the project root and commit it to version control so team members inherit the same automated rules:

# 1. Navigate to your project root
cd ~/projects/payment-service

# 2. Create the project skills directory
mkdir -p .claude/skills/pr-review-audit

# 3. Place the SKILL.md entrypoint
cp /path/to/SKILL.md .claude/skills/pr-review-audit/SKILL.md

# 4. Commit to git for team collaboration
git add .claude/skills/pr-review-audit
git commit -m "chore: add Claude Code pr-review-audit skill for CI review gate"

Once installed, restart or launch a new Claude Code session. Claude Code immediately indexes the skill container. If you need to verify team distribution patterns, check our guide on how to share Claude Skills with your team.

How Do You Invoke Claude Skills in Real Terminal Sessions?

Claude Skills can be invoked through two distinct interaction patterns: explicit command invocation by referencing the skill name, and semantic natural language invocation where Claude Code matches your prompt against the skill description.

Pattern 1: Explicit Command Invocation

When running an interactive Claude Code session, invoke the skill directly by typing a forward slash followed by the skill directory name, optionally passing parameters:

# Inside Claude Code CLI interactive prompt:
/pr-review-audit "Please audit the changes between origin/main and feature/auth-jwt"

Direct invocation forces Claude Code to bypass description ranking and immediately load the targeted SKILL.md instructions into the working context.

Pattern 2: Semantic Natural Language Invocation

You can also invoke the skill naturally without remembering slash syntax. Simply formulate a request that aligns with the terminology defined in your skill's YAML description:

claude "Review this pull request diff for unhandled async rejections and database index bottlenecks"

Claude Code evaluates the prompt against its indexed frontmatter registry. Because the phrase matches keywords and concepts defined in description: Comprehensive security and architecture audit for git pull requests..., Claude Code selects and executes pr-review-audit seamlessly.

How Do You Test and Verify That Claude Actually Executed the Skill?

Verifying skill execution requires auditing the agent's output structure and reasoning steps against the explicit constraints established in your SKILL.md instructions. A conversational or generic response indicates that Claude defaulted to base model behavior rather than adopting the skill.

If Claude Code fails to trigger the skill during semantic testing, inspect your YAML frontmatter indentation and check for special characters that violate YAML 1.2 rules. If errors persist, consult our step-by-step diagnostic in Claude Skills not working.

The Sprawl Moment: The Cost of Stranded Local Skills

A senior engineer authors a bespoke code-review and schema-migration skill with strict validation checklists on their primary MacBook Pro. When a staging regression occurs while they are traveling with an emergency backup laptop, the skill does not exist on the secondary machine. Recreating the prompt from memory in the terminal omits two critical database index checks, allowing an unoptimized table scan into production. The skill was technically functional, but because it remained stranded in a local filesystem directory, the workflow collapsed when the environment shifted.

Prompttly is a skill manager for AI agents — one library for your skills and prompts that syncs into Claude Code, Codex, ChatGPT, and Claude and is one hotkey away on your Mac, so your setup follows you across every machine, repo, and tool.

Instead of manually syncing directories across multiple laptops using fragile symlinks, Prompttly synchronizes versioned skills directly to ~/.claude/skills/ on your Mac while keeping the same workflows instantly callable via global hotkey palette. If you manage multiple machines or work with secondary computers, read our complete guide on how to sync Claude Skills across computers and how to sync prompts across laptops.

How Do Claude Skills Compare Across Cursor, Codex, and MCP?

While Claude Skills provide directory-scoped procedural modules for Claude Code, other AI agent environments rely on distinct configuration standards. The table below compares configuration models across 4 major AI execution environments:

Understanding these distinctions prevents configuration lock-in. While MCP handles external data and tool execution (such as connecting to a Postgres database or querying GitHub APIs), Claude Skills govern workflow logic, domain rubrics, and procedural decision-making. To understand the broader architectural trade-offs between agents, explore our deep dive on agent skills vs prompts and tools and our comparison of Claude Skills across projects.

Common Installation and Authoring Mistakes

• Exceeding frontmatter character limits: Writing a narrative description longer than 1,024 characters degrades semantic matching reliability during session startup.
• Copying only SKILL.md for multi-file skills: If your skill references secondary files (such as rubrics/security.md or templates/output.json), omitting those subdirectories causes file-not-found runtime errors.
• Naming collisions across personal and project scopes: If you have a personal skill named pr-review in ~/.claude/skills/ and a project skill with the same name in .claude/skills/, the project skill silently overrides the personal version.
• Hardcoding absolute filesystem paths: Writing rigid paths like /Users/name/projects into instructions breaks the skill immediately when shared with teammates or synced to another laptop. Always use relative paths or environment variables.
• Omitting negative trigger constraints: Without explicit negative boundaries ("Do not use for general chit-chat or style linting"), Claude Code may over-trigger on tangentially related prompts, wasting tokens and execution cycles.

Related Skills and Agent Resources

Continue building your AI workflow architecture with our comprehensive engineering guides:

• Agent Skills & Claude Skills Architecture — Complete guide to SKILL.md specification and execution models.
• Agent Skills & SKILL.md Guide — Comprehensive guide to agent skills, YAML frontmatter, token economics, and multi-agent execution.
• Claude Skills Across Projects — In-depth reference for personal vs project folder storage and resolution precedence.
• Multi-File Claude Skills — How to package complex modular skills with subdirectories and reference files.
• Claude Skills Troubleshooting — Diagnostic checklist for syntax errors, discovery failures, and misrouting.
• Sync Claude Skills Across Computers — Maintain continuous skill availability across multiple machines.
• Share Claude Skills With Your Team — Git repository conventions and governance for engineering organizations.
• Transfer Claude Code Settings to a New Computer — Migration checklist for moving machines.
• Prompttly Resources Hub — Full archive of AI agent, prompt engineering, and skill management guides.
• Free Claude Skill Creator — Generate production-ready SKILL.md packages with validated YAML frontmatter.
• Prompttly Mac App — Native macOS menu bar and global hotkey palette for instant agent skill access.

Frequently Asked Questions