Skill templates/Claude Code

Claude Code SKILL.md Template

A Claude Code skill is a SKILL.md file (plus optional supporting files) that Claude loads only when relevant, or that you invoke directly with /skill-name. It follows the Agent Skills open standard.

Where it lives

Project.claude/skills/<name>/SKILL.md

Personal~/.claude/skills/<name>/SKILL.md

Claude loads the skill automatically when the task matches its description, or you invoke it directly with /<skill-name>. (Custom commands have merged into skills.)

Skill structure

structure

my-skill/
├── SKILL.md      (required)
├── scripts/      (optional)
├── references/   (optional)
└── assets/       (optional)

Copy the SKILL.md

SKILL.md

---
name: ci-failure-fix
description: Use when CI is red and the failure is a concrete, reproducible check. Do not use for flaky infrastructure or product decisions.
---
 
# CI Failure Fix
 
## When to Use This Skill
Use when CI is red and the failure is a concrete, reproducible check.
 
## When Not to Use This Skill
Do not use for flaky infrastructure, secrets issues, or product decisions.
 
## Workflow
1. Read the CI logs and identify the failing check.
2. Reproduce the failure locally.
3. Apply the smallest fix.
4. Re-run the full relevant suite.
5. Summarize the root cause.
 
## Validation
- The CI command passes locally.
- The same failing test now passes.
- No unrelated tests are skipped or deleted.
 
## Safety Rules
- Do not remove failing tests.
- Do not disable lint or type checks.
- Stop and escalate if blocked.

Customize it in the SKILL.md Generator

Use it in a real task

A useful first trial is a branch with one reproducible lint failure. Give Claude the exact failing command and ask it to use the skill. The expected result is a small diagnosis, a local reproduction, the smallest relevant edit, the same command passing, and a handoff that stops before merge. Keep the original failing check in place so a green result still means something.

01
Create .claude/skills/ci-failure-fix/ inside the repository when the workflow belongs to one project, or use the personal skills folder only when the same rules truly apply across projects.
02
Save the copied template as SKILL.md, then replace the example trigger, validation command, forbidden actions, and escalation rule with the repository's real values.
03
Start a fresh Claude Code session in the target repository and invoke /ci-failure-fix, or describe a matching CI failure and confirm that Claude selects the intended skill.

Verify before relying on it

The skill appears in Claude Code and can be invoked by its exact name.
A matching request follows the stated workflow and runs the named validation rather than substituting a vague review.
An unrelated task does not trigger the skill, and a blocked run ends with the documented escalation instead of repeated guesses.

Common mistakes and recovery

Saving SKILL.md directly under .claude/skills without its own folder.

Give each skill a named directory so its supporting references and scripts remain isolated.

Using a broad description such as ‘helps with code.’

Name the observable trigger and the cases that must not activate the workflow.

Recovery path

If Claude does not load the skill, verify the folder and filename first, then shorten the description to one clear trigger and restart the session so discovery runs again. If the skill loads but takes unsafe shortcuts, do not add more motivational prose. Tighten the validation evidence, forbidden actions, and stop condition, then repeat the same small trial before using it on a larger repository change.

Good skill checklist

Front-load the key use case and trigger words in the description
Say clearly when the skill should and should not trigger
Keep the SKILL.md body short; move long material to references/
Make validation machine-checkable
Include explicit safety rules and an escalation condition

Sources

Claude Code — Skills Agent Skills standard