1. Choose one clear job
Start with a task that is repeatable, bounded, and easy to recognize. “Help with engineering” is too broad. “Review a database migration for unsafe locks, missing rollback steps, and deployment-order risks” gives the skill a clear trigger and expected result.
Write down three things before creating files:
- requests that should activate the skill;
- similar requests that should not activate it;
- observable qualities of a successful result.
This small test plan prevents a polished document from being mistaken for a reliable workflow.
2. Create a portable folder name
The Agent Skills specification requires a name of lowercase letters, numbers, and hyphens, with no leading, trailing, or consecutive hyphens. It must match the parent directory. Choose a stable task name rather than a version number or marketing phrase.
For a project-specific skill:
mkdir -p .claude/skills/migration-safety-review
Use ~/.claude/skills/ instead if the skill is personal and genuinely applies across projects.
3. Create SKILL.md
For cross-tool portability, include both required Agent Skills fields even though Claude Code supports additional or more permissive behavior in its own loader:
---
name: migration-safety-review
description: Review a proposed database migration for locking, data-loss, rollback, and deployment-order risks. Use before approving production schema changes.
---
# Migration safety review
Inspect the migration and its surrounding deployment context.
1. Identify destructive or blocking operations.
2. Check whether the change is safe with existing data.
3. Evaluate rollback and mixed-version application behavior.
4. Report evidence, severity, and a concrete mitigation.
Do not execute the migration. Mark unknown production conditions explicitly.
This is an original PiSkill example, not a copy of an Anthropic template. It separates the trigger in description from the procedure in the body and states a critical boundary: inspection does not authorize execution.
4. Write a useful description
The description is discovery metadata, not a slogan. State what the skill does and when to use it. Include distinctive task language naturally, but do not list every possible keyword. Keep the beginning informative because hosts may truncate descriptions in menus or context.
Compare these:
- Weak: “A powerful migration helper.”
- Better: “Review a proposed database migration for locking, data-loss, rollback, and deployment-order risks.”
The better description identifies the artifact, action, risks, and moment of use. It also creates testable expectations.
5. Keep instructions concise and operational
Write steps Claude can follow and evidence it should produce. Define required inputs, stopping conditions, output structure, and uncertainty handling. Include examples only when they clarify a difficult boundary or format.
Avoid long background essays in SKILL.md. Claude Code loads the full body when the skill is invoked and keeps those instructions in the conversation context. Move lengthy reference information to a focused supporting file so it is read only when needed.
6. Add supporting files only when needed
An original practical structure might be:
migration-safety-review/
├── SKILL.md
├── references/
│ ├── postgres-locking-notes.md
│ └── review-severity-rubric.md
├── assets/
│ └── report-template.md
└── scripts/
└── inspect-sql.sh
The skill should say when to open each reference and what the script does. Do not bundle files merely to look comprehensive. Every executable increases maintenance and review cost. Prefer deterministic scripts for mechanical inspection, never for silently bypassing permissions or performing unrelated actions.
7. Test triggering and behavior
Use at least four kinds of test:
- a direct invocation such as
/migration-safety-review path/to/change.sql; - a natural-language request that should trigger it;
- a nearby request that should not trigger it;
- an incomplete or risky input that should cause clarification or a safe stop.
Check whether the skill reads the intended files, follows the sequence, respects boundaries, and produces the expected structure. Test against realistic failure cases rather than only the happy path. Anthropic's current custom-skill documentation also points to the Agent Skills validation tool for structural checks.
8. Iterate from observed failures
If the skill fails to trigger, improve the description with clearer task and timing language. If it triggers too often, narrow the scope and add exclusions. If output is inconsistent, strengthen the procedure and provide a concise template. If instructions are ignored late in a long task, reduce competing material and keep critical constraints close to the relevant step.
Version skill changes through the same review process as code. Record why behavior changed and rerun the tests that exposed the problem. The verified Skill Creator and Writing Agent Skills directory records provide source-linked workflows for deeper evaluation.
Common mistakes
- Combining several unrelated jobs in one skill.
- Using a vague description that does not explain when to invoke it.
- Copying an example without adapting permissions, paths, and safety boundaries.
- Referencing files that are missing or installed at different paths.
- Adding broad tool permissions before the workflow requires them.
- Testing only direct invocation and never automatic discovery.
- Treating one successful response as proof of consistent behavior.
- Embedding secrets, private URLs, or machine-specific credentials.
Once the package is ready, follow the Claude Code Skills installation guide and verify its actual installed scope.