📁 Project .claude/skills/
The directory .claude/skills/ is at the root of your repository. Skills there have local scope — they exist only for people working on that specific project.
The directory .claude/skills/ at the repository root is the project-scoped skills space. Any 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—for example, .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 every sprint along with the project
- ✗ 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
- • Version-controlled in git
- • Shared with the team via clone
- • Scope: this project only
- • In the user’s home directory
- • Outside any repo
- • Only on your machine (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 precedence. 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—from a git clone — to the correct directory. That’s exactly how you install the skill explainer video of this course.
The skill can come from its own repository (github.com/inematds/video-explicativo), from a compressed folder, or simply from a folder sent by someone on the team. The minimum contents are always: SKILL.md at the folder root.
git clone https://github.com/inematds/video-explicativo. The skill is in skills/video-explicativo/ — this folder (with the SKILL.md at its root) that you move, not the entire repo.
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 by 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 is 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 — like npx skills add — which accesses a centralized catalog and downloads it automatically.
Tools like 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 right 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
- ✓ Want to ensure you have the latest version
- ✓ New team needs 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 into git. That means history, diffs, PR review, rollback, and full 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 looks different" without traceability.
Skills in ~/.claude/skills/ are outside any repository and are NOT versioned automatically. If you want a backup or history of 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
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 discrepancies between machines.
When the skill lives in .claude/skills/ in the repository, any git clone provides the complete environment. New developer on the team? Clone it and you have the skill. New machine? Clone it and it just works.
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, how to invoke it
- ✓ Include real usage examples in the SKILL.md
- ✓ Use a PR for any changes to the skill (review)
- ✓ Keep references up to date when the project changes
- ✗ Commit API keys or tokens inside the skill
- ✗ Skill with absolute paths that only exist on your machine
- ✗ Modifying 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 it uses it. Keep it as up to date as you would a README for a critical function.
📚 Module 1.4 summary
You’ve completed Track 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 local MP4s, with no cloud and no per-render cost — and how it connects to everything you learned about skills in Track 1.