What does installing a SKILL.md actually change?
Three things change the moment a skill folder lands somewhere your host reads. The agent gains a short description that tells it when to reach for the skill, a body of instructions it can load mid task, and on some hosts a list of tools it may use without stopping to ask you.
That third one is the part people skip. The file is Markdown, but Markdown that tells your agent to run a bundled script, post to an endpoint, or delete a directory is still a request your agent will carry out under your credentials. Review the package the way you would review a pull request from a contractor you have never met, because that is exactly what it is.
Stage the package before the agent can see it
mkdir -p ~/skill-review && cd ~/skill-review
git clone --depth 1 https://example.com/some-skill.git candidate
# every file, not just the one the listing advertised
find candidate -type f | sort
du -sh candidate
head -40 candidate/SKILL.mdThe inventory is the first real check, and it catches more bad packages than reading the prose does. A skill that advertises one Markdown file and ships a scripts directory, a compiled binary, or a single minified helper is not what the listing claimed. Count the files before you read them, and treat anything you cannot read as text as a reason to stop.
Then read for intent. You are not looking for clever code. You are looking for the handful of things that turn a helpful checklist into an outbound action: a host you do not recognize, a path to your environment file, or a line that tells the agent to proceed without confirming.
- Network calls: curl, wget, fetch, and any hardcoded host or webhook
- Credential reads: env files, keychains, token paths, cloud metadata addresses
- Consequential verbs: send, publish, deploy, delete, purchase, spend
- Language that tells the agent to skip confirmation or act without asking
- Base64 blobs, minified scripts, and any file that is not readable text
grep -rniE 'curl|wget|https?://' candidate/
grep -rniE 'API_KEY|SECRET|TOKEN|\.env|credential' candidate/
grep -rniE 'rm -rf|sudo|chmod|eval|base64 -d' candidate/
grep -rniE 'without asking|do not confirm|skip approval|auto-approve' candidate/What in the frontmatter can bypass your approval?
Claude Code reads a small set of frontmatter fields, and two of them decide who is in control of the session. Read the frontmatter before you read anything else, because it is short and it sets the ceiling on everything below it.
| Field | What it changes | Ask before you accept it |
|---|---|---|
| allowed-tools | Grants the listed tools with no prompt, for the turn that invokes the skill | Would you approve every one of these by hand? |
| disallowed-tools | Removes tools from the pool while the skill is active | Does the skill fence itself in, or leave everything open? |
| disable-model-invocation | Only you can trigger it; the model cannot start it | Should anything with side effects fire on its own? |
| description | Decides when the model reaches for the skill unprompted | Is the trigger narrow, or will it fire on half your prompts? |
Where does each host put the files?
Install location is not a filing detail. Put the folder in the wrong place and the skill is silently invisible, which reads as broken rather than misplaced. Put it in a shared location and it loads for every project on the machine, including client work it was never reviewed against.
| Host | Where the reviewed folder goes | Removal |
|---|---|---|
| Claude Code | Project scope in the repo, or personal scope in your home directory | Delete the skill directory |
| Hermes | One skills directory in your home folder, grouped by category | Remove the folder, then start a new session |
| OpenClaw | Workspace skills first, then project agent skills, then a global directory | Uninstall, then confirm no copy remains higher in precedence |
# Claude Code: project scope travels with the repo and gets reviewed with it
cp -r candidate .claude/skills/some-skill
# personal scope loads in every project on this machine
cp -r candidate ~/.claude/skills/some-skill
# Hermes: install by identifier, or copy the folder you already read
hermes skills install official/research/arxiv
cp -r candidate ~/.hermes/skills/some-skill
# OpenClaw: workspace wins over the project agents directory
openclaw skills install ./candidate
ls <workspace>/skills .agents/skills
# confirm what the host now sees
hermes skills list
openclaw skills listFlags move between releases, so the commands above are the bare forms. Check your host's current documentation before adding options, and list the directory afterward to confirm where the install landed. On Hermes a new skill takes effect in the next session, so one that appears to do nothing may simply not be loaded yet.
How do you rehearse a new skill without risking client work?
Rehearse in a folder you can delete. Copy in three fake records instead of a live export, point the agent at a test account, and give it a prompt that should trigger the skill. Then read what it did, not what it reported doing.
- Run the trigger once and read the full tool log, not the closing summary
- Confirm it stopped at every gate that would send, publish, deploy, or spend
- Check that nothing left the machine: no surprise request, no upload, no draft
- Delete the folder and confirm the skill drops out of the skill list
Is a SKILL.md safe because it is only Markdown?
No. Markdown is the delivery format, not the boundary. The file tells your agent what to do, and your agent already holds the tools that send email, write files, and call APIs. The risk sits in the permissions you granted the agent, so review every instruction with those permissions in front of you.
How do I know a skill has not changed since I reviewed it?
Pin the version. Record the commit or release you read, keep that reviewed copy in your own repository, and diff any update against it before you install the new one. Some registries publish scan and trust signals for a listing; treat those as one input to your review, never as clearance to skip it.
Should skills be installed per project or for the whole machine?
Per project by default. A project scoped skill is versioned with the repo, reviewed alongside it, and cannot follow you into unrelated client work by accident. Reserve machine-wide installs for skills you wrote or fully audited, and re-read that list every quarter to prune what you no longer use.
Get your business agent ready
Agent Ready is the free starting kit: the skill structure we use, the install review above as a checklist, and the approval gates we run on client work.
Agent Ready / Free beta