Claude Code Skills: Create, Install and Verify a Skill

Claude Code skills are reusable instructions and workflows that Claude loads when needed. You can ask Claude to use a relevant skill or invoke one with a slash command. A skill can turn a repeated review or handoff checklist into a procedure you can inspect and share. It does not require AMS. See Anthropic’s extension overview. This guide builds a small evidence-handoff skill: it reads the relevant project material and drafts a handoff that separates observations, test results and open questions. The first exercise stays local. An optional section explains how to share the result through AMS when independent tasks need a common conversation. Claude Code documentation reviewed 5 November 2026. The example targets local terminal sessions; cloud and account-synced skills have different discovery rules.

Skills, agents, instructions and MCP

You need	Use	Example in this workflow
A reusable procedure	A skill	Produce the same evidence-based handoff format when requested.
A worker with its own context	A subagent	Investigate a bounded question and return findings to the main session.
Project conventions across tasks	Instruction files such as `CLAUDE.md`	Record which tests matter and who owns a shared file.
Access to an external tool or service	An MCP connection	Give an authorized session access to messaging tools.

Anthropic’s subagent documentation explains separate worker contexts; its memory documentation covers project instructions. MCP supplies a tool connection, while a skill can describe how to use available tools. A skill normally runs in the current conversation. Adding context: fork requests a subagent context; a skill is not inherently another agent. Native teams and messaging are separate features: see running multiple Claude Code agents.

Prerequisites

A working local Claude Code installation and access to a project you can read. Follow Anthropic’s quickstart if needed.
Permission to add a skill folder in that project, or use your personal skills directory instead.
A specific handoff question and a file the reviewer can inspect, such as the project’s README.md.

The example needs no package installation, API key, MCP server or AMS account. Git is useful for identifying a revision but is optional.

Choose the installation scope

Scope	Skill location	Intended use
Project	`.claude/skills/evidence-handoff/SKILL.md`	Local sessions in this repository; share the folder through normal code review.
Personal	`~/.claude/skills/evidence-handoff/SKILL.md`	Local projects on your computer.
Managed	`.claude/skills/` under the managed settings directory	Organization-administered distribution.
Plugin	`skills/evidence-handoff/SKILL.md` inside a plugin	Distribution with a namespaced command such as `/plugin-name:evidence-handoff`.

Use the project location for this walkthrough. Local personal files do not automatically transfer to cloud sessions. Nested directories, linked worktrees and account-synced skills have additional rules; consult Anthropic’s skill location reference for your environment.

Create a small collaboration skill

1. Create the folder

From the intended project root:

mkdir -p .claude/skills/evidence-handoff

If that folder already exists, inspect it before changing anything. For a personal installation, use ~/.claude/skills/evidence-handoff throughout instead.

2. Write SKILL.md

Create .claude/skills/evidence-handoff/SKILL.md with this content:

---
name: evidence-handoff
description: Draft an evidence-based handoff for another coding agent or reviewer. Use when asked to summarize findings, report verification, or transfer a bounded task.
argument-hint: "[task or review question]"
disable-model-invocation: true
---

Prepare a handoff about: $ARGUMENTS

Read the applicable project instructions and only the files needed
for this question. Do not edit project files, launch other agents,
commit, publish, or send messages as part of this skill.

1. Identify the task, your scope, and any known file ownership.
   Do not infer another task's ownership or approval from silence.
2. If this is a Git checkout, inspect `git rev-parse --short HEAD`
   and `git status --short`. Identify the revision and relevant
   uncommitted changes; otherwise state that no Git revision is available.
3. Ground each finding in a file and line, an observed command result,
   or a supplied source. Separate your observations from reports by others.
   If a source is missing, name the gap instead of filling it in.
4. Report only checks actually performed, with command and outcome.
   Do not run extra tests just to fill the report. Mark unperformed
   checks as "not run" and explain what still needs verification.
5. Give the receiving reviewer one concrete next action. If the action
   could conflict with shared ownership, request acknowledgement first.

Return this in the conversation:

- Task and scope:
- Revision and relevant working-tree changes:
- Findings and evidence:
- Checks performed and results:
- Not verified or blocked:
- Next action and acknowledgement needed:

Never include credentials or private source content in a proposed
external handoff. Drafting a message does not mean it was sent,
read, acknowledged, or acted on.

The file uses YAML frontmatter followed by Markdown. Keep the opening --- on the first line. name and description identify the workflow; $ARGUMENTS receives the text after the command. disable-model-invocation: true makes this example manual. See the current frontmatter reference. The example deliberately leaves sending out of the procedure. A reviewer can inspect the evidence before deciding whether a teammate needs it. It also avoids pre-approving tools. A skill’s allowed-tools field grants permissions for listed tools; it is not a tool allowlist that blocks everything else. Use Claude Code’s permission settings for access controls.

3. Load and invoke it

For a static format check on Claude Code v2.1.233 or later, run this in the shell:

claude plugin validate .claude/skills

Expect a successful validation result. This checks skill metadata, not the quality of a generated handoff. Anthropic documents skill-directory validation in its troubleshooting reference. Start Claude Code from the project root:

claude

Inside Claude Code, enter:

/skills

Find evidence-handoff. If you added the folder during an existing session, run /reload-skills and check again. These are Claude Code prompt commands, not shell commands; Anthropic documents both in its command reference. Then send a message beginning with:

/evidence-handoff Summarize the setup requirements in README.md for a reviewer. Read the file and draft the handoff; do not change files or run tests.

Use an existing documentation file if your project has no README.md.

4. Verify the result

For this exercise, a successful response should:

Identify the file inspected and cite the lines supporting its setup findings.
Identify the Git revision and relevant uncommitted changes, or explain why those are unavailable.
State that tests were not run, without turning a README instruction into a claim that a test passed.
Give the reviewer a next action, such as checking one unresolved setup requirement.
Leave the project files unchanged and keep the handoff in the conversation.

Compare the citations with the actual file. In a Git project, compare git status --short before and after invocation; creating the skill itself is an expected change. A command appearing in the menu proves discovery, while an accurate report demonstrates the procedure’s usefulness. Try a second invocation against a path you know does not exist. The expected result is an explicit missing-source limitation, with no invented findings or successful checks. This tests the part of the handoff most likely to mislead another agent. For repeat use, try realistic handoff questions in fresh sessions and compare the reports against a short checklist. Anthropic’s authoring guidance recommends concrete examples and evaluation rather than relying on one successful response. For automatic selection, remove disable-model-invocation: true and keep a precise description of when to use the skill. user-invocable: false instead hides a skill from direct user invocation. Existing .claude/commands/ files still work, but use a SKILL.md folder for new skills. See invocation controls. To install a reviewed skill from someone else, put its complete folder in your chosen skill location, preserving any relative supporting files, then repeat the discovery and behavior checks above. Read its instructions, scripts and permission grants before using it. A Markdown procedure can still direct consequential actions. For team distribution, review the project skill alongside your code, or use Anthropic’s plugin installation workflow for a trusted plugin. This walkthrough does not install a marketplace package or publish a plugin. Use AMS when separate tasks or tools need a shared channel for findings, ownership decisions and review requests. Keep the local skill above as the drafting step. Claude Code’s native subagents, teams and skill loading work without AMS. For the CLI path, first complete the AMS quickstart and deliberately enable the intended folder using repository workspace setup. Have each agent run the following from its actual working folder:

ams workspace current --json

Only if it succeeds with enabled: true, continue:

ams --require-workspace status
ams --require-workspace messages --resume

Confirm the intended workspace and channel, with a distinct host-supplied identity for each task. Read each returned page in order and repeat the resumed read if the footer says (more available). If activation is disabled or invalid, leave AMS off and resolve setup deliberately. After reviewing the draft and authorizing a send to that channel, save the approved text to a local file and use:

ams --require-workspace send --file /absolute/path/to/reviewed-handoff.txt

Replace the path with the file you reviewed. A successful send confirms storage. The recipient must read the message and respond before you treat an ownership or interface request as accepted. Storage does not wake an inactive agent or prove it acted; a separate host-supported continuation is needed where applicable. If you prefer MCP, follow Claude’s AMS connection guide. Copying this SKILL.md neither configures MCP nor authenticates AMS. The example is a user-authored teaching skill, not an AMS skill package. For a full tester/builder exchange, see Claude Code and Codex together.

Troubleshooting

Symptom	Check
The command is missing	Verify the exact `SKILL.md` filename, selected scope and project directory. Run `/reload-skills`, then `/skills`.
Asking for a handoff does not trigger it	This example is manual. Start the message with `/evidence-handoff`, or deliberately change its activation field.
Another skill runs	Check for the same name in managed or personal locations; personal skills take precedence over project skills. Rename your example if needed.
Metadata seems ignored	Check YAML syntax and the first-line delimiter against the frontmatter reference.
The report cites files it did not read	Reject those findings. Narrow the question and repeat the exercise with inspectable source material.
A reported check has no result	Mark it unverified. A planned command, a README instruction and an executed passing check are different evidence.
A teammate has not replied	Check its active session and next read. Do not equate message storage or silence with acknowledgement.

For discovery and trigger failures, use Anthropic’s skill troubleshooting guide. Keep project-wide rules in your shared instructions so the workflow remains useful beyond a single invocation.

The example was checked against the linked documentation, and the extracted SKILL.md passed a local claude plugin validate check. No authenticated Claude Code skill run or live AMS exchange was performed for this tutorial. Run the exercise in your own environment to verify discovery, permissions and output quality.

Get started

Build with AMS

MCP

Compare and connect coding agents

Skills and hooks

Agent workflows

Claude Code Skills: Create, Install and Verify a Skill

Skills, agents, instructions and MCP

Prerequisites

Choose the installation scope

Create a small collaboration skill

1. Create the folder

2. Write SKILL.md

3. Load and invoke it

4. Verify the result

Troubleshooting

Skills, agents, instructions and MCP

Prerequisites

Choose the installation scope

Create a small collaboration skill

1. Create the folder

2. Write SKILL.md

3. Load and invoke it

4. Verify the result

Control activation and share the skill

Optional: share a verified handoff through AMS

Troubleshooting