Skip to content

Agent Skills: Why SKILL.md Won't Load + Fix Guide

This guide solves 3 problems:

  1. Why your SKILL.md isn't loading (and how to verify)
  2. How to write descriptions that trigger matching
  3. A minimal, working template you can copy

Quick Diagnostic

If your skill isn't being selected:

  1. Check file location: .github/skills/<name>/SKILL.md or .claude/skills/
  2. Validate with SDK: skills-ref validate ./my-skill
  3. Confirm frontmatter: name and description are required YAML fields
  4. Test matching: Does your description include the keywords the user would type?

Still stuck? See Top 7 Reasons Skills Fail below.

Minimal Template

---
name: my-skill
description: Short summary. Use for keyword1, keyword2, topic.
---
## Goal
...
## Procedure
1. ...
2. ...

Top 7 Reasons Your Skill Isn't Selected

#SymptomCauseFix
1Skill never loadsFile not in .github/skills/ or .claude/skills/Move SKILL.md to correct location
2Validation failsMissing name or description in frontmatterAdd required YAML fields
3Name mismatchname field doesn't match folder nameRename folder or update name
4Invalid name formatUppercase, spaces, or consecutive hyphensUse lowercase, numbers, single hyphens only
5Skill loads but never triggersDescription lacks trigger keywordsAdd "Use for X, Y, Z" with user-typed terms
6Wrong skill selectedMultiple skills with overlapping descriptionsDifferentiate keywords, add negative examples
7Tool/agent doesn't support skillsUsing older version or unsupported toolUpdate CLI, enable chat.useAgentSkills in VS Code

Symptom-by-Symptom Fixes

1. Skill never loads

  • Verify path: ls .github/skills/my-skill/SKILL.md
  • Run skills-ref validate ./my-skill
  • Check for typos in folder structure

2. Validation fails

  • Ensure YAML frontmatter starts with --- and ends with ---
  • Required fields: name, description

3. Name mismatch

# Folder: .github/skills/terraform-plan-review/
# SKILL.md name field must be:
name: terraform-plan-review

4. Invalid name format

  • ❌ Terraform-Plan (uppercase)
  • ❌ terraform--plan (consecutive hyphens)
  • ✅ terraform-plan-review

5. Description lacks keywords

# Bad
description: Helps with infrastructure reviews.

# Good
description: Standardize Terraform plan diff reviews. Use for Terraform, plan, diff, IAM, network, cost topics.

6. Overlapping skills

  • Add unique keywords to each skill's description
  • Consider merging similar skills

7. Tool doesn't support skills

  • GitHub Copilot: Supported (Dec 2025+)
  • VS Code: Enable chat.useAgentSkills in settings
  • Codex CLI: v0.76.0+ required

Description Design Patterns

The description field determines when your skill is selected. Here are patterns that work:

Good Examples

# Pattern 1: Task + Keywords
description: Standardize Terraform plan diff reviews. Use for Terraform, plan, diff, infrastructure review, IAM, network, cost topics.

# Pattern 2: Problem + Solution
description: Fix failing CI builds by analyzing logs and suggesting fixes. Use for CI, build failure, GitHub Actions, pipeline debug.

# Pattern 3: Domain + Actions
description: Generate release notes from git history. Use for release, changelog, version, git log, notes.

Bad Examples

# Too vague - won't match specific queries
description: Helps with infrastructure reviews.

# Missing trigger keywords
description: A comprehensive solution for code analysis.

# Too long - buries the keywords
description: This skill provides a complete end-to-end solution for reviewing and analyzing infrastructure-as-code changes including but not limited to Terraform, Pulumi, and CloudFormation templates with a focus on security best practices and cost optimization strategies.

Key Principles

  1. Front-load keywords: Put the most important terms in the first sentence
  2. Include "Use for X, Y, Z": Explicitly list trigger keywords
  3. Match user vocabulary: Use terms users actually type, not internal jargon
  4. Keep it under 200 characters: Longer descriptions dilute matching

🔗 Official Docs vs This Guide

SourceWhat It CoversWhat This Guide Adds
agentskills.io SpecificationFormal spec, SDK referenceDebugging workflow, description patterns
VS Code Agent Skills DocsEnabling skills, basic structureTop 7 failure reasons, fix checklist
OpenAI Codex SkillsCodex-specific setupCross-tool compatibility notes
Agent Skills QuickstartPre-built vs custom, 3-minute introDeep debugging, templates

What Are Agent Skills

Agent Skills are instructions (Markdown) plus supplementary resources (scripts/references/templates) bundled into a single folder — an open standard format that agents load "only when needed."

Progressive Disclosure is Key

  1. At startup, only name/description (metadata) is read
  2. The SKILL.md body loads when determined necessary
  3. Additional files like references/ or scripts/ load only if further needed

Skills vs Custom Instructions vs MCP

Use CaseBest ForExamples
Custom InstructionsRules common to almost all tasks (always on)Naming conventions, lint policies
Agent SkillsProcedural knowledge + assets loaded when conditions matchRelease procedures, incident triage
MCPExternal APIs and operationsDatabase access, Slack integration

MCP adds "what can be done" (APIs/operations), while Skills provide "how to use them" (procedural knowledge).

Supported Tools (December 2025)

ToolStatusNotes
GitHub Copilot✅ SupportedCopilot coding agent, CLI, VS Code agent mode
VS Code✅ Stable (1.109+)Enable chat.useAgentSkills
OpenAI Codex✅ Supportedv0.76.0+ required
Cursor✅ SupportedListed on agentskills.io
Claude Code✅ SupportedOrigin of Skills (.claude/skills)

Folder Location

.github/skills/<skill-name>/SKILL.md  ← Recommended (GitHub Copilot / VS Code)
.claude/skills/                        ← Legacy location (still supported)

GitHub Copilot auto-recognizes .claude/skills/, so existing Claude Code skills work as-is.

name Field Specification

ConstraintDetails
Length1-64 characters
AllowedLowercase (a-z), numbers (0-9), hyphens (-)
Start/EndCannot start or end with hyphen
Consecutive hyphens-- not allowed
Directory nameMust match parent folder name

Valid: pdf-processing, data-analysis, code-review, terraform2Invalid: PDF-Processing, -pdf, pdf--processing

Example: Terraform Plan Review Skill

# .github/skills/terraform-plan-review/SKILL.md
---
name: terraform-plan-review
description: Standardize Terraform plan diff reviews. Classify plan changes and prioritize inspection of destructive changes, permission changes, network changes, and cost impacts. Use for Terraform, plan, diff, infrastructure review, IAM, network, cost topics.
license: Proprietary
metadata:
  author: platform-team
  version: "0.1"
compatibility: Requires terraform CLI and access to repo IaC code.
---

## Goal
Conduct Terraform plan reviews comprehensively and consistently.

## Inputs
- `terraform plan` output (text or JSON)
- Target module/environment (dev/stg/prod)

## Procedure
1. **Classify changes** (Resource type / Impact scope / Environment)
2. **Detect destructive changes** (delete/replace)
3. **IAM/permissions** (role/policy/binding additions or relaxations)
4. **Network** (ingress/egress, public exposure, SG/NSG)
5. **Data protection** (KMS, encryption, backup, retention)
6. **Estimate cost impact** (new major resources, scale increases)
7. **Rollback strategy** (on apply failure, state consistency)

## Output format
- Summary: What changes (3 lines)
- Risks: Critical risks (bullet points)
- Checks done: Inspection points completed
- Questions: Unclear points (for PR comments)

Validation with SDK

# Installation
pip install skills-ref

# Validate a skill
skills-ref validate ./my-skill

# Read properties (JSON output)
skills-ref read-properties ./my-skill

Add validation to CI for team stability.

FAQ

How does skill matching work?

At startup, agents read only name and description. The body loads when the agent determines the skill is relevant based on keywords in description. Progressive disclosure keeps context efficient.

Why isn't my skill selected even though it's valid?

Your description may lack the keywords users type. Add "Use for X, Y, Z" phrases that match expected queries. Also check for conflicting skills with overlapping triggers.

How do I avoid conflicts between multiple skills?

Give each skill a distinct set of trigger keywords. If two skills overlap significantly, consider merging them or adding negative examples ("Do NOT use for...") to clarify boundaries.

Summary

ItemContent
What are Agent SkillsOpen standard: SKILL.md + scripts/references/assets in folders
Progressive disclosureStartup: name/description → when needed: body → additional resources
Supported toolsGitHub Copilot, VS Code, OpenAI Codex, Cursor, Claude Code
Recommended location.github/skills/<skill-name>/SKILL.md
Minimal structureYAML frontmatter (name/description required) + Markdown body
Success keysTrigger keywords in description, fix procedures + output formats
ValidationIntegrate skills-ref validate into CI