Skill templates/Open standard (any agent)

SKILL.md Template (Agent Skills open standard)

The Agent Skills open standard (agentskills.io) defines a vendor-neutral SKILL.md: a name, a description of when to use it, and the workflow. Claude Code and Codex both implement it.

Where it lives

Open standard.agents/skills/<name>/SKILL.md

Most tools load the skill when the task matches its description, or let you invoke it by name. Keep the description scoped and trigger-word-rich.

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 portable first trial is documentation link repair. Provide a fixture with one confirmed broken internal link, require the agent to reproduce it, edit only the responsible document, rerun the link checker, and stop for review. The workflow is general enough to compare across tools while the success condition, forbidden shortcut, and evidence remain objective.

01
Start with the standard directory shape and keep SKILL.md as the only required file; add scripts, references, or assets only when the target agent actually supports and needs them.
02
Write the description around a portable task signal rather than a vendor command, then document any vendor-specific install path outside the shared skill body.
03
Test the same fixture in each target tool separately because support for discovery, invocation, supporting files, and permissions can differ even when the file format is shared.

Verify before relying on it

Each target tool recognizes the skill from its documented install location rather than from a one-off prompt pasted into the session.
The tool follows the shared validation and stop rules without depending on an unsupported vendor-only command.
Results are recorded per tool, including discovery failures and permission differences, rather than claiming universal compatibility from one successful run.

Common mistakes and recovery

Assuming one directory works in every agent implementation.

Keep the SKILL.md portable, but verify and document the actual install location for each target tool.

Hiding vendor-specific behavior inside the shared workflow.

Separate the common task contract from optional tool adapters and test those adapters independently.

Recovery path

If one tool ignores the skill, first check that tool's documented discovery path and supported frontmatter instead of weakening the shared workflow for every implementation. When a vendor requires different invocation or supporting files, keep a small adapter beside the portable core. Mark unverified tools as untested, retain the known-good fixture, and repeat it after any format or product update.

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

Agent Skills standard Codex — Agent Skills