📁 Project .claude/skills/
The directory .claude/skills/ stays at the root of your repository. Skills there have local scope — they exist only for those working on that specific project.
The directory .claude/skills/ at the repository root is the project-scoped skills directory. Every skill placed there is available only when Claude Code is running inside that repo.
Each skill is a subfolder. The folder name is exactly the name Claude recognizes it by — e.g., .claude/skills/video-explicativo/.
- ✓ The skill is specific to that product or client
- ✓ You want to version the skill alongside the code
- ✓ The whole team needs to use the same version of the skill
- ✓ The skill changes with the project each sprint
- ✗ The skill is for all your personal projects
- ✗ The repo is public and the skill contains sensitive data
- ✗ You’re testing a temporary draft
- ✗ The skill needs to work outside any project
🌐 ~/.claude/skills/ global
The global directory is in ~/.claude/skills/ (user's home directory). Skills there apply to absolutely any project you open on the machine.
- • Inside the repository
- • Tracked in git
- • Shared with the team via clone
- • Scope: this project only
- • In the user's home directory
- • Outside any repo
- • On your machine only (not cloned)
- • Scope: all projects
If a skill with the same name exists in both places (local and global), the local version (.claude/skills/) takes priority. Use this to your advantage: add a customized version of a skill you normally use globally to the project.
📋 Install by copying the folder
The simplest way to install a skill is to copy the folder—or extract a .zip — in the correct directory. This is exactly how you received the skill explainer-video of this course.
The skill can come as a compressed folder (video-explicativo.zip), a separate repository, or simply a folder shared by someone on the team. The minimum content is always: SKILL.md in the folder root.
If you received a zip: unzip video-explicativo.zip. The result should be a folder with the skill name as its root—confirm before moving it.
For local scope: mv video-explicativo/ .claude/skills/. For global scope: mv video-explicativo/ ~/.claude/skills/. Create the directory if it doesn't exist: mkdir -p .claude/skills/.
Open Claude Code in the project session. The skill will already be available — just invoke it using the name configured in the SKILL.md. No restart or reload required.
There are no binaries, no build, and no npm dependencies to install. A skill consists of 100% text files: Markdown, shell scripts, and templates. Copying the folder IS the complete installation.
⌨️ By command
Besides copying manually, you can install skills via CLI—such as npx skills add — which accesses a centralized catalog and downloads automatically.
Tools such as npx skills add <nome> abstract away the manual copying process: they find the package in the catalog, download it, and automatically place it in the correct location.
It’s the same pattern as npm install but for Claude Code skills — no package.json, no node_modules, just the skill folder.
- ✓ Public skills from the official catalog
- ✓ You want to ensure you have the latest version
- ✓ New team members need to set up the environment quickly
- ✓ You want to explore the catalog of available skills
- ✗ Internal/private company skills (not published)
- ✗ You need a specific custom version
- ✗ Environment without internet access
- ✗ The skill is still in local development
🔁 Version control with git
A skill is plain text — so it fits naturally in git. That means history, diffs, PR reviews, rollbacks, and complete traceability of who changed what in the skill.
When the skill and code evolve together in the same commit, you always know exactly which version of the skill produced which output. No more “the skill changed and the video looked different” without traceability.
Skills in ~/.claude/skills/ stay outside any repository and are NOT versioned automatically. If you want a backup or history for your global skill, create a dedicated repository (e.g., meus-skills-pessoais/) and synchronize manually.
Write SKILL.md + references → git add + commit
Fix the prompt, add a reference → new commit — visible diff in the PR
The team reviews skill changes the same way it reviews code — line-by-line comments
git tag v1.2-skill — freezes the skill in a stable state for production
🤝 Share with the team
A skill in the repository means every developer who clones the project automatically gets the same skills — no manual installation, no differences between machines.
When the skill lives in .claude/skills/ in the repository, any git clone provides the complete environment. New dev on the team? Clone it and you have the skill. New machine? Clone it and it works right away.
This eliminates the question "which version of the skill are you using?" — everyone uses exactly what's in the repo's current commit.
- ✓ Document the skill in the README: what it is and how to invoke it
- ✓ Include real usage examples in SKILL.md
- ✓ Use a PR for any skill changes (review)
- ✓ Keep references up to date when the project changes
- ✗ Commit API keys or tokens inside the skill
- ✗ Skill with absolute paths that exist only on your machine
- ✗ Modify the skill without communicating changes to the team
- ✗ Skill that depends on software not listed in the prerequisites
git clone <repo>ls .claude/skills/The skill’s SKILL.md isn’t just instructions for Claude — it’s real documentation of what the team uses and how. Keep it as up to date as you would a README for a critical function.
📚 Module 1.4 Summary
You’ve completed Learning Path 1 — Skills. Here’s everything you’ve mastered:
.claude/skills/ from the project — scope limited to the repository
~/.claude/skills/ — available in any project on the machine
npx skills add automate downloading the catalog
Track 2 — Pipeline. Discover the open-source framework that turns animated HTML into a local MP4, with no cloud and no per-render cost — and how it connects to everything you learned about skills in Track 1.