Installing a Claude Code skill from GitHub requires three things: finding the SKILL.md and its associated files in the repository, copying the entire skill folder to the correct location on your machine, and verifying the install with the /skills command in a fresh session. The correct location is .claude/skills/skill-name/ at your project root for project-level skills, or ~/.claude/skills/skill-name/ for skills available across all your projects. This guide is drawn from AEM's production skill engineering work across hundreds of commissions.

TL;DR: Copy the skill folder — not just the SKILL.md — into .claude/skills/ at your project root. Open a fresh Claude Code session and run /skills to confirm it appears. If it doesn't show up, check the folder placement and the description field format. Evaluate the skill's quality before relying on it in real work.

How Do I Find the Skill Files in a GitHub Repository?

Claude Code skills are folder-based, not single files. A skill lives in a folder named after the skill, and that folder contains the SKILL.md plus any reference files, including supporting documents the SKILL.md references at runtime. Copying only the SKILL.md leaves out those references, and the skill will fail on any step that tries to load them.

What to look for in a GitHub repository:

repository-root/
  .claude/
    skills/
      skill-name/         ← copy this entire folder
        SKILL.md
        references/
          some-reference.md

Some repositories store skills at the root level without the .claude/skills/ wrapper:

repository-root/
  skill-name/             ← copy this entire folder
    SKILL.md
    references/

In both cases, what you need is the folder named after the skill. Do not copy just the SKILL.md — you'll get the skill body but miss all reference files it depends on.

If the repository README doesn't indicate which folder structure it uses, look for the SKILL.md file and work outward from there: the folder containing SKILL.md is the skill folder. The Claude Code skill ecosystem now holds over 85,000 indexed skills across platforms (OpenAIToolsHub, 2026), which means format and structure vary widely across community repositories. GitHub alone hosts over 14,000 repositories containing Claude Code skills or plugins as of April 2026 (awesome-claude-plugins, 2026), and their folder conventions are not standardized.

Where Do I Place the Skill Files on My Machine?

Claude Code looks for skills in two locations: project-level at .claude/skills/ inside your project directory, and user-level at ~/.claude/skills/ in your home directory. Project-level skills are available only in sessions started from that project. User-level skills load in every Claude Code session regardless of which project you open.

  • Project-level: .claude/skills/ inside your project directory. Skills here are available only in sessions started from that project.
  • User-level: ~/.claude/skills/ in your home directory. Skills here are available in all Claude Code sessions regardless of which project you're in.

Both paths expect the same structure:

your-project/
  .claude/
    skills/
      skill-name/
        SKILL.md
        references/

~/.claude/skills/
  skill-name/
    SKILL.md
    references/

For most community skills, project-level installation is the right choice. It keeps the skill scoped to the context where you need it. User-level installation makes sense for utility skills you use across every project — code review skills, commit message formatters, documentation generators.

In our experience at AEM, the most common installation failure isn't a missing file — it's a misplaced one. Skills placed at the project root directly, or inside .claude/ without the skills/ subdirectory, are invisible to Claude Code. Across AEM commissions in 2026, path errors accounted for more than half of all first-install failures reported by clients (AEM commission data, 2026). The path must be exactly .claude/skills/skill-name/SKILL.md.

How Do I Verify the Installation Worked?

Open a fresh Claude Code session in the project directory where you installed the skill and run /skills. Claude Code lists every skill it has successfully read at session start, identified by the description field in the SKILL.md frontmatter. Present means loaded. Absent means a path or frontmatter problem needs fixing before the skill will work.

/skills

Claude Code will list all installed and recognized skills with their description fields. If your new skill appears, the installation worked.

If it doesn't appear, check these in order:

  1. Path: Is the skill at .claude/skills/skill-name/SKILL.md? Run ls .claude/skills/ to confirm the folder exists.
  2. Description field: Open the SKILL.md and confirm the description field is on a single line in the frontmatter, under 1,024 characters (Claude Code specification). A description that wraps to a second line, or is missing entirely, causes the skill to be skipped during discovery.
  3. YAML frontmatter: The frontmatter must start and end with --- on their own lines. A malformed frontmatter block prevents Claude Code from reading the description.
  4. Session freshness: Skills are loaded at session start. Restart your Claude Code session after installation, not mid-session.

The /skills command is your diagnostic tool. If it lists the skill, Claude Code has successfully read the description and loaded it into the startup context. Analysis of Claude Code auto-execution failures finds that 99% trace to one of three configuration issues: incorrect file path specifications, frontmatter syntax errors, or permission problems (SmartScope, 2026). Path and frontmatter issues are exactly what /skills surfaces.

"The failure mode isn't that the model is bad at the task — it's that the task wasn't specified tightly enough. Almost every production failure traces back to an ambiguous instruction." — Simon Willison, creator of Datasette and llm CLI (2024)

That observation applies to installation too. A skill that fails to load is almost always a path or frontmatter problem, not a Claude Code bug.

What Should I Evaluate Before Relying on a Community Skill?

Installation and functionality are separate questions. A skill that installs correctly and appears in /skills can still fail to work reliably: the description field controls discovery, but it does not guarantee the skill's trigger logic, output contract, or reference files are production-grade. Verify the skill before depending on it.

Before using a community skill in real work, run four checks:

  1. Trigger test: Open a fresh session and describe the task the skill is designed for in natural language. Does the skill activate automatically? If not, the description field isn't triggering — either it's too passive, it conflicts with another installed skill, or it's mismatched to how you described the task.
  2. Output contract check: Read the SKILL.md. Does it define what the skill produces and what it does not produce? An undefined output contract means you'll get whatever Claude Code decides to give you, not a consistent deliverable.
  3. Reference file check: If the skill has reference files, verify they're loading. Ask Claude Code to confirm it read the reference file as part of skill execution.
  4. Edge case test: Run the skill on an input different from the example in the README. A skill that works on the example but fails on your actual inputs is a fair-weather skill.

Among developers who use AI agents regularly, 71% use Claude Code as their primary tool (gradually.ai, 2026). That scale of adoption means community skills are being installed into production workflows by teams that cannot afford a fair-weather skill. Run these four checks before any skill touches real work.

For the complete quality checklist, see What Makes a Community Skill Production Ready.

For installing skills from SkillsMP specifically, which has a slightly different process, see How Do I Install a Community Skill from SkillsMP into My Project.

What Do I Do If the Skill Has Dependencies I Don't Have?

Read the SKILL.md requirements section before installing. If no requirements section exists, read the README.md at the repository root. A skill that calls an MCP tool or references a local script has external dependencies. Installing it without those dependencies in place produces steps that fail with no error message pointing at the missing piece.

Common dependency problems:

  • MCP servers: If the skill calls MCP tools (Notion:create_page, GitHub:create_issue), you need those MCP servers configured. Installing the skill without the MCP server results in steps that fail silently. MCP adoption has reached 82.1% among Claude Code users in 2026 (Skywork, 2026), so MCP-dependent skills are now the norm in community repositories, not the exception.
  • External tools: Some skills reference local tools or scripts that must exist on your machine.
  • Claude Code version: Skills written for Claude Code 2.x may use commands or behaviors not available in 1.x.

If the skill has undocumented dependencies, this is a signal about skill quality. A well-built distributable skill states its requirements explicitly. See How Do I Write a Skill That Works for Other People's Projects for what a properly documented skill looks like.

Frequently Asked Questions

Most installation questions reduce to two root causes: wrong path placement and missing dependencies. The skill folder must be at exactly .claude/skills/skill-name/ with a well-formed SKILL.md frontmatter, and every MCP server or external tool the skill calls must be configured before you run it for the first time.

Do I need to clone the entire GitHub repository to install a skill? No. You only need the skill folder and its contents. Download the specific folder using GitHub's download directory feature, or clone the repository and copy only the skill directory. Most community skill repositories contain a single skill and are small enough to clone entirely.

Can I install multiple skills from the same repository? Yes. If the repository contains multiple skill folders under .claude/skills/, copy each one independently. Each skill folder is independent.

What happens if I install a skill with the same name as one I already have? The new skill overwrites the existing one. Make a backup of your current skill folder before installing a replacement version.

Will installing a community skill affect my other installed skills? It can, if the new skill's description is too broad and starts triggering on prompts meant for your existing skills. Install in a fresh session and test for conflicts using /skills and natural-language trigger tests. See What Causes Multiple Skills to Interfere with Each Other for the diagnosis process.

How do I keep a community skill updated when the author releases a new version? Check the GitHub repository for updates and repeat the installation process — download the new version and overwrite the existing files. Some plugin-format skills support update commands. Bare SKILL.md installations require manual updates.

Is there a way to install a skill with a single command instead of copying files manually? Yes, for skills distributed in plugin format. Plugin-packaged skills install with a single command that handles file placement automatically. See What's a Claude Code Plugin and How Does Packaging Skills as Plugins Help Distribution for how plugin format works.

Last updated: 2026-04-26