How to install Agent Skills in Claude Code and Claude.ai
Where skill folders go in Claude Code, how to package and upload a skill to Claude.ai, and how to check that Claude actually loads it.
A skill is a folder with a SKILL.md file inside. The file starts with YAML frontmatter between --- markers, followed by Markdown instructions. Claude reads the description to decide when the skill is relevant, and loads the full instructions only when it uses the skill. Claude Code skills follow the Agent Skills open standard, so the same folder can work in other tools that support it.
---
name: page-meta-check
description: Check the SEO head tags of one web page and return a pass/fail table. Use when the user asks to audit the title or meta description of a URL.
---
# Page meta check
Step-by-step instructions for Claude go here.
Install a skill in Claude Code
1. Choose where the skill should load
| Location | Path | Loads in |
|---|---|---|
| Personal | ~/.claude/skills/<skill-name>/SKILL.md |
All your projects on this machine |
| Project | .claude/skills/<skill-name>/SKILL.md |
Sessions in that repository. Commit it so your team gets it too |
Personal skills are not read by Cowork or cloud sessions. For those, enable the skill on your Claude.ai account (see below) or commit it to the repository’s .claude/skills/.
2. Put the folder there
If you downloaded a ZIP whose top level is the skill folder, unzip it straight into the skills directory:
mkdir -p ~/.claude/skills
unzip page-meta-check.zip -d ~/.claude/skills/
# result: ~/.claude/skills/page-meta-check/SKILL.md
Don’t name a skill folder synced. Claude Code reserves that name for skills downloaded from Claude.ai.
3. Reload if needed
Claude Code watches ~/.claude/skills/ and the project’s .claude/skills/, so adding or editing a skill there is picked up in the current session without a restart. If the top-level skills directory didn’t exist when the session started, run /reload-skills.
4. Check that it works
- Type
/skillsto see the list, or ask Claude “What skills are available?” - Ask for something that matches the skill’s description, or invoke it directly with
/page-meta-check.
If Claude doesn’t use the skill, put the words people would naturally say into the description. The frontmatter is only read when the opening --- is the first line of the file. If the YAML doesn’t parse, the skill loads with no metadata, so /skill-name still works but Claude can’t match it automatically. Start Claude Code with claude --debug to see the parse error.
To remove a personal or project skill, delete its folder.
Upload a skill to Claude.ai
1. Turn on code execution
Skills are available on Free, Pro, Max, Team and Enterprise plans and need code execution.
- Free, Pro and Max: open Settings → Capabilities and turn on Code execution and file creation.
- Team and Enterprise: an Owner checks that code execution and Skills are enabled under Organization settings → Plugins & skills, on the Policy tab.
2. Package the skill as a ZIP
The ZIP must contain the skill folder itself at the top level, and the folder name must match the name field in SKILL.md. A SKILL.md sitting at the root of the ZIP is not recognized.
zip -r my-skill.zip my-skill/
unzip -l my-skill.zip # every entry should start with my-skill/
Claude.ai uploads only accept these frontmatter fields: name, description, license, compatibility, metadata and allowed-tools. Claude Code accepts more fields, such as argument-hint, but uploading a skill that uses one fails with an “Unexpected key(s)” error.
3. Upload and turn it on
- Go to Customize → Skills.
- Click +, then + Create skill, then Upload a skill.
- Choose your ZIP. The skill appears in your list and can be toggled on or off.
- Try a few prompts that should trigger it, and check Claude’s thinking to confirm it loads the skill.
Common upload failures: the ZIP is too large, the folder name doesn’t match the skill name, SKILL.md is missing, or the name or description has invalid characters.
Use your Claude.ai skills in Claude Code
When you sign in to Claude Code in a terminal with your Claude.ai account, it downloads the skills enabled on that account into ~/.claude/skills/synced/ (Claude Code v2.1.273 or later). They appear under “claude.ai sync” in /skills. Edit synced skills on Claude.ai, not in that folder, because the next sync overwrites local changes.
Before you install anyone’s skill
Read the files first. A skill can include scripts, and its allowed-tools frontmatter can pre-approve tools for the turn that invokes it. Anthropic’s docs advise reviewing the allowed-tools of skills checked into a repository before running Claude Code there. Don’t put API keys or passwords in a skill you share: everyone you share it with receives its files.
Sources
- Claude Code docs: Extend Claude with skills
- Claude Help Center: Use skills in Claude
- Claude docs: Create custom skills (packaging)
- Claude Help Center: How to create custom skills
Products change. If a step no longer matches what you see, the official page above is the reference.
Related on Skillaisle
- SkillPage Meta Check