sample-agent-skills-for-builders AGENTS.md

AGENTS.md

This file provides guidance to AI coding agents (Claude Code, Cursor, Copilot, etc.) when working with code in this repository.

Repository Overview

A collection of sample skills for AI coding agents. Skills are packaged instructions and scripts that extend agent capabilities. This repository follows the Agent Skills format.

Creating a New Skill

Directory Structure

skills/
  {skill-name}/           # kebab-case directory name
    SKILL.md              # Required: skill definition with frontmatter
    metadata.json         # Optional: extended metadata
    references/           # Optional: supporting documentation
    scripts/              # Optional: executable scripts

Naming Conventions

• Skill directory: kebab-case (e.g., my-awesome-skill, code-reviewer)
• SKILL.md: Always uppercase, always this exact filename
• Scripts: kebab-case.sh (e.g., deploy.sh, validate.sh)

SKILL.md Format

Every skill MUST have a SKILL.md file with YAML frontmatter:

---
name: {skill-name}
description: {One sentence describing when to use this skill. Include trigger phrases like "Deploy my app", "Review this code", etc.}
license: MIT
metadata:
  author: {author-name}
  version: "1.0.0"
---

# {Skill Title}

{Brief description of what the skill does.}

## When to Apply

Reference this skill when:
- {Condition 1}
- {Condition 2}
- {Condition 3}

## How It Works

1. {Step 1}
2. {Step 2}
3. {Step 3}

## Usage

{Show examples with code blocks}

## References

- {Link to documentation}
- {Link to related resources}

Required Frontmatter Fields

Field	Required	Description
name	Yes	Unique identifier in kebab-case
description	Yes	One sentence with trigger phrases for discovery
license	No	Defaults to repository license (MIT)
metadata	No	Extended metadata object

Best Practices for Context Efficiency

Skills are loaded on demand. Only the skill name and description are loaded at startup. The full SKILL.md loads into context only when the agent decides the skill is relevant.