SKILL.md Template

SKILL.md is a standardized Markdown file with YAML metadata that packages reusable instructions and workflows for AI agents. Loaded on demand when a task matches its description, it lets tools like Claude Code, Cursor, and Codex execute specialized tasks consistently without bloating prompts.
name: <Lowercase letters, numbers, and hyphens only (1–64 chars). Must match the parent folder name.>
description: <Explains what the skill does and use when user says "...">
license: <License name (e.g., MIT, Apache-2.0) or reference to a bundled license file.>
allowed-tools: <Pre-approves specific tools so they can run them without permission prompts while the skill is active. For example,
  - Read
  - Grep
  - Bash(aws sts get-caller-identity:*)
  - Bash(aws ec2:*)
  - Bash(bash -n:*)
  - Bash(./scripts/create-vpc.sh:*)
>
metadata:
  version: "1.0.0"
  author: <author>
  updated_date: "yyyy-mm-dd"

Purpose

One or two sentences stating what the workflow accomplishes and any prerequisites.

Prerequisites Checklist

  • [ ] Python 3.8 or higher installed
  • [ ] huggingface_hub package installed
  • [ ] Valid Hugging Face account
  • [ ] HF_TOKEN environment variable set

Instructions

Numbered phases or imperatives telling the agent exactly what actions to take in order.

Rules

Conditional logic ("If X, do Y"), edge-case handling, and explicit constraints on what not to do.

Output Format

Concrete samples showing the exact format, tone, or structure you expect.

References

Relative links to supporting files inside the skill folder so the agent only reads heavy docs when required.

The SKILL.md body supports special template variables and shell injection syntax that are evaluated before executing the prompt
Syntax Behavior Example
$ARGUMENTS Expands to the full string passed after /skill-name. Fix issue #$ARGUMENTS
$ARGUMENTS[N] / $N Accesses a specific whitespace-separated positional argument (0-indexed). Compare $0 with $1
!`command` Executes a shell command at load time and injects its stdout directly into the prompt before Claude processes it. !`git status --short`