Claude Code skills: write, install and scan them safely

Claude Code skills are folders with a SKILL.md file that teach Claude a repeatable task, such as reviewing a PR or cutting a release, and Claude loads one only when your request needs it. That makes skills the right home for instructions that matter for some tasks but not every session. The catch is that a skill is instructions your agent will follow, so a skill from the internet deserves the same care as a script from the internet.

This post covers the skill format, where skills live, how Claude picks them, how to write a good one, and how to find and install shared skills without handing your agent something dangerous.

What a Claude Code skill is

A skill is a folder. The only required file is SKILL.md:

---
name: release-notes
description: Use when the user asks for release notes or a changelog entry for a version.
---

1. Run `git log --oneline <last-tag>..HEAD`.
2. Group the commits into Features, Fixes and Other.
3. Write one plain sentence per change, for users, not developers.
4. Ask before writing to CHANGELOG.md.

The frontmatter holds the name and the description. The body is the instruction Claude follows once the skill is loaded. The folder can also hold scripts and reference files that the instructions point to, so a skill can say “run scripts/check.sh” or “read reference/api.md for the endpoint list”.

Where Claude Code skills live

The folder name becomes the command, so .claude/skills/release-notes/SKILL.md can also be run as /release-notes. Type /skills in a session to list the skills Claude sees. For the rest of the slash commands, see the Claude Code commands cheat sheet.

How Claude decides to use a skill

At the start of a session Claude sees the skills’ descriptions, not their full bodies. When your request matches a description, it loads that skill. Two things follow from this:

• The description does the routing. “Release notes skill” is a weak description. “Use when the user asks for release notes or a changelog entry for a version” tells Claude when to reach for it.
• Skills keep your base context small. Only the descriptions load every session, so moving task-specific instructions out of CLAUDE.md and into skills keeps every turn lighter. More on that in Claude Code context window.

Skills, CLAUDE.md, subagents and MCP

These four overlap, so it helps to know which one fits.

If you are pasting the same paragraph into prompts twice a week, it should be a skill. If you need the agent to talk to a database or an API, that is an MCP server (what an MCP server is).

How to write a good skill

1. Start from a task you already repeat. Write down the steps you type today.
2. Write the description as a trigger. Start with “Use when…” and name the words a user would say.
3. Keep the body short and ordered. Numbered steps beat paragraphs.
4. Put long material in files. A reference table or a script goes next to SKILL.md, and the body says when to read or run it.
5. Say what not to do. “Ask before writing to CHANGELOG.md” prevents the surprise you would otherwise fix by hand.
6. Test it in a fresh session. Ask for the task in your own words and check that Claude picks the skill without being told.

The risk in shared skills

Sharing skills is where they get useful, and risky. A skill can tell your agent to run a shell command, read a file outside the project or send something to a URL. If your agent runs with broad permissions, a malicious or careless skill runs with them too. Things to look for before installing one:

• Destructive or privileged commands (rm -rf, sudo)
• Reading secrets, such as .env files or SSH keys
• Sending data out to a host you do not know
• Download-and-run patterns, such as piping curl into a shell
• Obfuscated code or hidden Unicode characters
• Prompt injection: text that tries to override your instructions

The AI coding agent security post covers permissions and sandboxing in more depth.

Managing skills in AgentVera

AgentVera’s skill gallery is under a project’s Details page, Automation → Skills. It has three views: Local, Discover and My published.

Local lists the skills on your computer for both agents that use skill folders:

From there you can:

• Create one with New skill: pick the Agent (Claude Code or Codex), the Scope (This project or All projects), a Name (lowercase letters, digits and hyphens) and When should it be used?, which becomes the description. Create and edit opens the new SKILL.md.
• Turn a skill off without deleting it. The switch moves the folder to a place the CLIs do not scan.
• Preview or edit SKILL.md, copy a skill to the other agent or scope, or delete it, which moves the folder to the Trash.

Finding and installing skills safely

Discover shows your organization’s skills and the public gallery. Search, pick one of 10 categories (coding, testing, code review, DevOps, data, docs, design, security, productivity, other), filter by agent and sort by Popular or New. The same gallery is on the web at app.agentvera.dev/skills.

Each skill’s detail view has Files, Security and Versions tabs. The Security tab shows the Server scan. The scan looks for destructive or privileged commands, secret reading, embedded keys, data sent out, download-and-run, obfuscated code, prompt injection, hidden Unicode, raw IP addresses and outside hosts. Results run from clean through info, low, medium and high risk to critical.

Installing is two steps:

1. Download and scan. AgentVera downloads the files, verifies their SHA-256 and scans them again on your computer.
2. Install. Scripts are written as plain files and are not made executable.

Agents see the skill in their next session. When a new version is published, an update button shows up next to the installed skill. Gallery skills install only for the agents they support, Claude Code and Codex.

Public skills pass a security scan and moderator review, but still look over the findings and the files. The scan catches patterns; you know what your project should and should not do.

Sharing your own skills

With a Pro or Team plan and an AgentVera account, Share publishes a local skill. You give it a title, a 20 to 300 character summary, up to 6 tags, a category and a version like 1.0.0, with a changelog for each version. A skill is limited to 50 text files, 256 KB per file and 1 MB in total.

• Organization only: visible to your organization right away if the scan finds nothing high or critical; otherwise it is refused.
• Public: waits for moderator approval, and critical findings are not accepted. Track it in My published.

Skills and token use

Every skill adds its description to the base context. A handful is fine; dozens of personal skills add up on every turn. AgentVera’s Lean context profile does not load user-level skills, which is one of the reasons its first request is smaller (measured here). Keep project skills in the repo and prune personal ones you no longer use.

Summary

Claude Code skills turn repeated prompts into folders Claude loads on demand: a SKILL.md with a clear “use when” description, short ordered steps and any scripts it needs, in .claude/skills for the project or ~/.claude/skills for you. Shared skills are worth it only if you check them first. AgentVera lists Claude Code and Codex skills in one place, scans gallery skills on the server and again on your computer before install, and lets Pro and Team users publish their own. Download AgentVera to manage your skills.