How to Install and Use Claude Code Skills: Complete Step-by-Step Guide

To master how to install claude code skills, place your skill folder containing a valid SKILL.md file directly into either ~/.claude/skills/ for personal use or .claude/skills/ for project-level scope. Claude Code detects directory contents automatically, parses frontmatter metadata, and dynamically loads execution scripts on demand without server restarts.

• Progressive Context Disclosure: Keeps token overhead minimal by indexing concise descriptions and loading detailed operational instructions only when semantically triggered.
• Zero-Dependency Execution: Leverages portable bash, Python, or Node scripts directly inside the skill directory, bypassing heavy background server runtimes.
• Dual Scope Control: Switch cleanly between global developer workflows (~/.claude/skills/) and team-wide, repository-specific automation (.claude/skills/).
• Effortless Team Synchronization: Version control project skills using standard Git repositories or Git submodules to guarantee uniform agent behavior across engineering teams and CI/CD pipelines.
• Instant CLI Verification: Validate installed capabilities in seconds with the native /skills interactive command inside the Claude Code terminal environment.

Understanding Claude Code Skill Scopes: Personal vs Project

Before installing skills, you must select the appropriate scope. Claude Code supports two distinct operational layers: global personal scope and project-level team scope. Choosing the right scope determines whether capabilities persist across all terminal sessions or stay isolated to a specific repository.

1. Global Personal Scope (~/.claude/skills/)
Located in your user home directory, skills placed here are globally accessible across every terminal session, project, and directory on your local machine. This scope is ideal for personal productivity utilities, custom git review assistants, universal debugging helpers, and workflow automations tailored to your individual development environment.

2. Team Project Scope (.claude/skills/)
Located at the root of a specific codebase, skills placed here are bound to that repository. When committed to source control (such as GitHub or GitLab), project skills ensure that every developer, staging environment, and automated CI runner shares identical agent capabilities, coding standards, and deployment runbooks.

The structural layout of a well-formed Claude Code skill follows a modular, predictable directory tree:

.claude/
└── skills/
    └── git-release-manager/
        ├── SKILL.md                 # Core specification and prompt instructions
        ├── schemas/
        │   └── release-config.json  # Input/output validation schemas
        ├── scripts/
        │   ├── bump-version.sh      # Executable automation script
        │   └── generate-changelog.py
        └── references/
            └── semver-rules.md      # Extended context loaded on demand

Step 1: Anatomy of a SKILL.md File

The core foundation of every skill is its SKILL.md file. This file combines standard Markdown documentation with YAML frontmatter. Claude Code relies on the YAML header for cataloging, tool indexing, and natural language semantic routing.

The description attribute is the single most critical field. When a session starts, Claude Code loads only the name and description into its active context window. If your prompt matches the intent expressed in the description, Claude Code automatically opens and reads the rest of the SKILL.md instructions. Writing a specific, action-oriented description guarantees reliable agent triggering without wasting token budget.

Here is an authentic, production-ready SKILL.md example:

---
name: database-migration-validator
description: Validates PostgreSQL and MySQL schema migration files for destructive operations, missing rollback scripts, and missing indexes. Use whenever creating or reviewing database migration files before deployment.
---

# Database Migration Validator

Inspect all newly created SQL files in `db/migrations/` or `prisma/migrations/`.

## Mandatory Validation Rules
1. Flag any raw `DROP COLUMN`, `DROP TABLE`, or `TRUNCATE` operations without explicit fallback checks.
2. Ensure every non-nullable column added to existing tables includes a default value.
3. Validate that foreign key references include an associated index to avoid sequential full-table scans.

## Execution Workflow
When the user asks to validate migrations:
1. Identify staged or recent SQL files using `git status` or `git diff`.
2. Execute the verification script:
   ```bash
   ./scripts/validate-schema.sh <path-to-sql-file>
   ```
3. Report any violations as blockers, along with suggested non-destructive SQL alternatives.

Step 2: Installing Pre-Built Skills in Under 2 Minutes

Installing a Claude Code skill involves moving the skill directory into the target scope. You can install pre-built skills using two straightforward methods.

Method A: Manual Drop or ZIP Extraction

Download curated, production-tested skill packages directly from the AiCodePro AI Skills Directory. Extract the downloaded folder directly into your chosen directory:

# For Global Personal Scope:
mkdir -p ~/.claude/skills
cd ~/.claude/skills
unzip ~/Downloads/code-review-optimizer.zip

# For Project-Specific Scope:
cd /path/to/your/project
mkdir -p .claude/skills
cd .claude/skills
unzip ~/Downloads/code-review-optimizer.zip

Method B: Direct Git Clone or Team Git Submodule

For team environments, installing skills via Git submodules guarantees that any upstream improvements or security patches can be updated with a single git command:

# Option 1: Global Personal Installation via Git Clone
cd ~/.claude/skills
git clone https://github.com/aicodepro/git-release-manager.git

# Option 2: Project-Level Installation via Git Submodule (Recommended for Teams)
cd /path/to/your/project
git submodule add https://github.com/aicodepro/git-release-manager.git .claude/skills/git-release-manager
git commit -m "feat(ai): integrate git-release-manager Claude Code skill"

For advanced installation patterns, including symbolic linking across monorepos, multi-environment token inheritance, and customized script execution, read the comprehensive AiCodePro Skills How-To Guide.

Step 3: Verifying and Testing Installed Skills

Once you place the skill files in the directory, launch Claude Code to confirm that the agent discovers and validates them.

Start an interactive session in your terminal:

claude

Inside the interactive prompt, execute the skills inspection slash command:

/skills

The terminal will print a structured overview of all detected skills, categorized by scope (Personal vs. Project). Review this list to verify that your new skill appears with its expected identifier and frontmatter description.

Next, perform an end-to-end operational test by prompting Claude Code with a task that aligns with the skill's description:

> Check the database migration script in db/migrations/004_add_user_roles.sql for any safety violations.

Observe Claude Code read the underlying SKILL.md, inspect the file rules, invoke the designated script in ./scripts/, and return structured output. If Claude Code recognizes the skill automatically, your installation is complete.

Managing, Updating, and Removing Skills

Maintaining a dependable set of agent skills requires applying the same software engineering standards you use for production dependencies:

• Enforce Script Execution Permissions: Helper scripts packaged inside skill folders (such as .sh or .py files) must have executable rights. On macOS and Linux, run:

  chmod -R +x ~/.claude/skills/*/scripts/

• Version Pinning and Upgrades: If you use Git submodules for project-level skills, pin them to specific release tags or commit hashes to prevent unexpected upstream changes from altering agent behavior in production or CI:

  cd .claude/skills/git-release-manager
  git checkout v1.2.0
  cd ../..
  git commit -am "chore: pin git-release-manager skill to v1.2.0"

• Environment Variables and Credential Hygiene: Never hardcode API keys, tokens, or credentials inside SKILL.md or companion scripts. Rely on standard local environment variables (such as GITHUB_TOKEN, AWS_PROFILE, or DATABASE_URL) exported in your shell profile or injected by continuous integration pipelines.
• Clean Uninstallation: To remove a skill, delete the corresponding subfolder:

  rm -rf ~/.claude/skills/database-migration-validator

Comparison: Installing Skills vs Configuring MCP Servers

Developers often ask whether to build a custom Claude Code skill or configure an external Model Context Protocol (MCP) server. The table below details how the two architectures compare:

Sources

• Anthropic Official Documentation
• Anthropic Skills Specification
• AiCodePro Skills Directory