SKILL.md: Writing Skills That Work Across Agents

Start with one recognizable task

A useful skill captures a procedure you would otherwise explain repeatedly: reviewing staged changes, inspecting a database schema or preparing a release note. Choose one outcome with a clear completion condition. A skill called engineering-helper gives the agent little basis for deciding when to load it; review-staged-changes identifies an operation and its input.

The Agent Skills specification requires YAML frontmatter followed by Markdown. Both name and description are required. The name must match its parent directory, contain only lowercase letters, numbers and hyphens, and fit within 64 characters; leading, trailing and consecutive hyphens are prohibited. The description has a 1,024-character limit.

Treat those as format constraints. Your editorial job is to make the skill distinguishable from adjacent procedures. Define what the agent should produce before choosing its name.

Write the description for selection

The specification describes progressive disclosure: names and descriptions are available before the full instructions load. A trigger hidden halfway down the body cannot help an agent select a skill it has not opened. Put the action, relevant input and likely user phrasing in the description.

Compare Helps with code quality with Reviews Git changes staged for commit and reports concrete bugs, whitespace errors and missing verification. Use when the user asks to review staged changes or check a patch before committing. The second description gives the agent a task boundary without claiming every code-related request.

Write three matching requests before finalizing it: “Review what I staged,” “Check this patch before I commit,” and “Find bugs in my staged changes.” Then try neighboring requests such as “Explain Git staging” and “Write a commit message.” If those also select the review skill, narrow the description or split the competing responsibilities.

Give the agent an executable contract

Here is a complete starting file for review-staged-changes/SKILL.md. Its commands come from the Git diff manual; the review policy and output requirements are an example you can adapt.

---
name: review-staged-changes
description: >-
  Reviews Git changes staged for commit and reports concrete bugs,
  whitespace errors and missing verification. Use when the user asks
  to review staged changes or check a patch before committing.
compatibility: Requires Git and terminal access in the target repository.
---
# Review staged changes

Produce a review of the staged patch without changing the repository.

## Procedure
1. Work from the repository root. Run git diff --cached --name-only.
   If nothing is staged, report that and stop.
2. Read git diff --cached to inspect the staged patch.
   Do not substitute unstaged changes for staged evidence.
3. Run git diff --cached --check. Record its output and exit status.
   A failure here is a check result, not a reason to skip the review.
4. Report bugs supported by the patch. Explain each failure condition
   and cite the relevant file and changed lines. Separate unresolved
   questions from confirmed findings.
5. Return a change summary, findings and verification results.
   Explicitly list checks that were not run.

## Boundaries
Do not edit, stage, commit, install dependencies or contact services.
If Git or terminal access is unavailable, explain what is missing.
Never report an unexecuted check as passing.

Git documents --cached as inspecting staged changes, while --name-only lists changed filenames. The --check option reports introduced conflict markers or whitespace errors and returns a nonzero status when it finds problems. Passing it says nothing about the patch's application logic.

Specify failures as carefully as successful output

The important portability test is what happens when a prerequisite disappears. This example requires a shell and Git. An agent that can only call remote tools cannot perform the same review merely because it can read the Markdown. The compatibility field declares that requirement; the body tells the agent how to respond when it is unmet.

Distinguish an empty staged patch from a command failure. Distinguish a failed whitespace check from an unavailable check. Otherwise, two agents can produce equally confident reviews after observing entirely different evidence.

Keep boundaries close to the procedure. “Review this patch” should not quietly expand into editing files, installing a test runner or committing fixes. If you want an editing workflow, write its authorization boundary explicitly. For distributed skills, review these instructions together with any bundled executable files; reviewing untrusted skills covers that separate decision.

Move detail out with explicit reading conditions

The Agent Skills authoring guide recommends concise procedures and conditional references. For this review skill, keep the command sequence and output contract in SKILL.md. Put a lengthy project-specific review checklist in references/review-checklist.md, then say exactly when to read it: “Read references/review-checklist.md before assessing changes to authentication.”

Resolve supporting paths relative to the skill directory. Do not assume the agent's current working directory is that directory: the Git commands above run in the repository, while a bundled helper belongs to the skill package. State both locations when they differ.

Avoid turning the body into a directory listing that requires opening every reference. Each reference should answer a named question encountered during the procedure. Package mandatory references with the skill so copying the main file does not silently remove essential instructions.

Keep installation and client extensions explicit

For a repository skill, Claude Code documents .claude/skills/review-staged-changes/SKILL.md. Cursor documents project discovery under both .agents/skills/ and .cursor/skills/, plus compatibility with Claude skill directories. Choose a documented location for each target client and verify that it discovers the intended copy.

Claude Code extends the standard with features such as dynamic context injection and invocation controls. Keep those out of the shared procedure unless each target documents the behavior you need. Writing “run git diff --cached” lets the agent execute an instruction; using a client's automatic command substitution makes loading depend on that client's interpreter.

The specification also marks allowed-tools experimental, with implementation-dependent support. Do not treat that field as a portable permission boundary. Cursor additionally warns that local user skills are not automatically copied to remote workers. Verify the installed package in the execution environment. For distributing approved copies, continue with a shared skills repository.

Serving shared skill text through SPYN3

SPYN3's opt-in Memory & skills setting stores shared skills at spyn3://workspace/skills/<name>/SKILL.md. Any MCP client can use context_list, context_read and context_search; reading requires call:tools, while writing requires write:memory. An admin enables the setting, which is off by default. Use it to hold the reviewed procedure text, then verify how each client retrieves and applies it. Fetching text through MCP does not establish native skill discovery or provide the Git environment required by this example.

Test discovery and behavior separately

Use a disposable repository with a known staged patch to evaluate this skill. The Agent Skills evaluation guide recommends clean contexts, observable assertions and comparison with a baseline. For portability, run the same fixtures in each intended client and record its version.

1. Verify discovery: confirm the installed skill's name and description are available before requesting a review.
2. Test selection with matching and neighboring prompts. Record unwanted activations as well as missed ones.
3. Invoke the skill explicitly to isolate execution failures from selection failures.
4. Try an empty index, a staged bug, a whitespace error and a file containing both staged and unstaged edits. Check which evidence the agent actually uses.
5. Remove terminal access. Require an explanation of the missing prerequisite rather than a fabricated review.
6. Compare findings and command records with a run without the skill. Check that the procedure improves the review and preserves repository contents.

A correct final format can hide a skipped command. Inspect the execution record, then revise the particular instruction responsible for the failure. Keep a skill only when its guidance produces a repeatable improvement on the tasks it claims to handle.