AGENTS.md — Contributor Guidance

Comprehensive guidance for AI agents and human contributors creating, maintaining, and extending skills in this repository.

Repository Overview

This repository contains 389 skills organized into 14 top-level categories. Each skill is a self-contained directory with a SKILL.md definition file and generated companion files.

Skill Categories

Hierarchy Model

Skills use a 2-3 level nesting hierarchy:

skills/
  {category}/                  # Level 1: broad domain
    SKILL.md                   # Category overview + navigation
    {subcategory}/             # Level 2: topic grouping
      SKILL.md                 # Subcategory overview
      {skill}/                 # Level 3: specific skill
        SKILL.md               # Deep technical content

• Level 1 (category): Broad domain overview, knowledge map, sub-skill navigation table
• Level 2 (subcategory): Medium scope, groups related skills, may contain deep content
• Level 3 (leaf skill): Specific, deep technical content with code examples and rules

Every directory in the hierarchy that contains skills must have its own SKILL.md — this is how discovery works.

Skill Directory Contents

Each skill directory contains these files:

Complete directory structure

skill-name/
  SKILL.md            # Required: frontmatter + full instructions (manual)
  metadata.json       # Required: machine-readable metadata (generated)
  AGENTS.md           # Required: agent-optimized content (generated)
  README.md           # Required: human-readable documentation (generated)
  rules/              # Optional: individual rule files (generated)
    _template.md      #   Rule authoring template
    _sections.md      #   Index table of all rules
    {name}-{slug}.md  #   One file per best practice
  scripts/            # Optional: executable helpers (manual)
    install.sh        #   Install/configure the tool
  references/         # Optional: supporting documentation (manual)
    REFERENCE.md
  assets/             # Optional: templates, images, data (manual)

Progressive disclosure (token efficiency)

Skills are designed for layered loading to minimize token consumption:

1. Level 1 — Metadata (~100 tokens): name and description from SKILL.md frontmatter loaded at startup for discovery
2. Level 2 — Instructions (<5000 tokens): Full SKILL.md body loaded when the skill is triggered
3. Level 3 — Resources (as needed): Scripts, references, and rule files loaded only when required

Keep SKILL.md body under 5000 tokens. Move detailed reference material into rules/, references/, or scripts/.

SKILL.md — Skill Definition

The primary skill file has two parts:

1. YAML frontmatter (between --- fences) with metadata
2. Markdown body with the skill content (instructions, rules, examples)

Frontmatter specification

Required fields

Optional fields

Naming rules

• Lowercase letters, hyphens, and digits only (e.g., aspnet-core, blazor, a2a)
• Maximum 64 characters
• Must match the directory name — the name field and containing directory must be identical
• No underscores, spaces, or uppercase letters
• Abbreviations stay lowercase: mcp, cli, jwt, rbac, spa, pwa

Minimal frontmatter

---
name: my-skill
description: "Use when working with My Framework to follow best practices."
---

Full frontmatter

---
name: my-skill
description: |
  Use when working with My Framework for configuration, routing, and middleware.
  USE FOR: framework setup, route configuration, middleware patterns, error handling
  DO NOT USE FOR: deployment (use iac skills), database access (use data skills)
license: MIT
metadata:
  displayName: "My Framework"
  author: "Tyler-R-Kendrick"
  version: "1.0.0"
  tags:
    - typescript
    - web
    - framework
compatibility: claude, copilot, cursor
---

Description patterns

The description field is the primary discovery mechanism. Agents use it to decide when to load a skill.

Structure

description: |
  [Value proposition — what this skill helps with, 1-2 sentences]
  USE FOR: [3-5 comma-separated trigger phrases]
  DO NOT USE FOR: [2-3 anti-triggers with redirects to sibling skills]

Guidelines

• Start with a trigger phrase: "Use when working with X..." or "Use when designing Y..."
• Use multi-line YAML format (|) for descriptions over 200 characters
• Keep total description under 1024 characters
• Include USE FOR: with 3-5 specific trigger phrases
• Include DO NOT USE FOR: with anti-triggers that redirect to sibling skills
• Be specific about when the skill should activate so discovery works well

Examples by skill type

Library/package skill:

description: |
  Guidance for FastAPI web framework — async endpoints, dependency injection, Pydantic models.
  USE FOR: creating REST APIs with FastAPI, dependency injection, request validation, OpenAPI docs
  DO NOT USE FOR: Django or Flask projects (use django/flask), database ORMs (use sqlalchemy)

Architecture/strategy skill:

description: |
  Use when designing authentication and authorization systems. Covers OAuth 2.0, JWT, RBAC/ABAC.
  USE FOR: auth design, OAuth flows, JWT implementation, session management, RBAC, ABAC
  DO NOT USE FOR: API endpoint design (use api-design), security scanning (use security-testing)

Category/parent skill:

description: |
  Root skill for Python development. Covers project configuration, package management, CLI tools.
  USE FOR: Python project setup, choosing tools, understanding the Python ecosystem
  DO NOT USE FOR: specific package usage (use packages sub-skills)

Tool skill:

description: |
  Guidance for Git version control — branching strategies, workflows, hooks, and advanced operations.
  USE FOR: git commands, branching, merging, rebasing, hooks, submodules, worktrees
  DO NOT USE FOR: CI/CD pipelines (use iac), GitHub API (use tools)

Body section patterns

The markdown body follows consistent section patterns depending on skill type.

Standard section order

# Skill Title

## Overview
[2-3 sentence summary of what this technology/pattern is and why it matters]

## [Core Concepts / Key Features]
[Fundamental building blocks — definitions, diagrams, concept tables]

## [Topic Sections — 3-6 sections covering major areas]
[Detailed content with code examples, tables, patterns]

## Best Practices
[5-10 bulleted recommendations — these get extracted into rules/]

Section patterns by skill type

Content conventions

• Code blocks: Always include the language tag (```typescript, ```python, ```csharp)
• Tables: Use standard markdown tables (no merged cells). Include a "Best For" or "Use When" column in comparison tables.
• ASCII diagrams: Use for architecture flows, hierarchies, and communication patterns. Wrap in ``` blocks.
• Inline code: Use backticks for function names, config keys, CLI commands (e.g., useEffect, pyproject.toml)
• Links: Reference official documentation URLs where helpful
• Comparison matrices: Common for tool selection, pattern evaluation, and framework comparisons

Best Practices section format

The ## Best Practices section should be the last section in the body. It uses bulleted lists:

Simple format (most common):

## Best Practices

- Always use virtual environments. Never install project dependencies into system Python.
- Commit your lockfile for reproducible builds.
- Use `>=` with minimum versions for libraries, exact pins for applications.

Bold-prefix format (for named principles):

## Best Practices

- **Defense in depth**: never rely on a single security control; layer multiple defenses.
- **Least privilege**: grant only the minimum permissions necessary for each component.
- **Secure defaults**: ship with the most restrictive configuration by default.

Both formats are supported. Use bold-prefix when practices have well-known names. Aim for 5-10 items. These bullets are automatically extracted into rules/ files by generate-rules.py.

metadata.json — Machine-Readable Metadata

Generated from SKILL.md frontmatter. Used for tooling, indexing, and discovery.

{
  "version": "1.0.0",
  "name": "my-skill",
  "displayName": "My Skill",
  "description": "Use when working with My Framework to follow best practices.",
  "author": "Tyler-R-Kendrick",
  "license": "MIT",
  "date": "February 2026",
  "compatibility": "claude, copilot, cursor",
  "references": []
}

Regenerating

python scripts/generate-skill-files.py

AGENTS.md — Agent-Optimized Content

The per-skill AGENTS.md contains the markdown body from SKILL.md without frontmatter. This is the pure agent-consumable content loaded when the skill is triggered.

Regenerating

python scripts/generate-skill-files.py

README.md — Human Documentation

Each skill's README.md provides human-readable documentation:

• Skill display name and description
• File structure table (includes rules/ count when present)
• Sub-skills listing (for parent skills with child directories)
• Installation command (npx agentskills add ...)
• License

Regenerating

python scripts/generate-skill-files.py

Rules

The rules/ directory decomposes a skill's Best Practices section into individual rule files, following the Vercel agent-skills pattern. Rules are auto-generated from ## Best Practices bullets by generate-rules.py.

Rule file format

---
title: "Use Promise.all() for independent operations"
impact: CRITICAL
impactDescription: "2-10x improvement in async performance"
tags: async, parallelization, promises
---

## Use Promise.all() for independent operations

When async operations have no interdependencies, execute them concurrently.

**Incorrect:**

```typescript
const user = await fetchUser()
const posts = await fetchPosts()

Correct:

const [user, posts] = await Promise.all([fetchUser(), fetchPosts()])

### Rule frontmatter fields

| Field | Type | Description |
|-------|------|-------------|
| `title` | string | Rule name/title |
| `impact` | string | `CRITICAL`, `HIGH`, `MEDIUM`, or `LOW` |
| `impactDescription` | string | Brief explanation of why this matters |
| `tags` | string | Comma-separated tags for categorization |

### Impact levels

| Level | Meaning | Keyword triggers |
|-------|---------|-----------------|
| **CRITICAL** | Essential for correctness or security | "never", "always", "must", "security", "credential", "production" |
| **HIGH** | Significant quality or reliability improvement | "ensure", "validate", "prevent", "avoid", "enforce" |
| **MEDIUM** | General best practice | Default for most rules |
| **LOW** | Recommended but situational | "consider", "prefer", "optionally", "where possible" |

### Special files in rules/

| File | Purpose |
|------|---------|
| `_template.md` | Template for manually authoring new rules — includes Incorrect/Correct code example placeholders |
| `_sections.md` | Index table listing all rules with impact level and file link |

### Rule file naming

Files are named `{skill-name}-{kebab-case-slug}.md`:
- `security-defense-in-depth.md`
- `react-use-function-components-with-hooks.md`
- `docker-use-multi-stage-builds.md`
- `fastapi-use-apirouter-to-organize-endpoints-by-domain.md`

### Generating rules

```bash
# Generate rules/ directories from Best Practices sections
python scripts/generate-rules.py

# Preview without writing files
python scripts/generate-rules.py --dry-run

# Verbose output (shows skipped skills)
python scripts/generate-rules.py --verbose

Skills without a ## Best Practices section are skipped (~51 skills). Skills with best practices get a rules/ directory containing _template.md, _sections.md, and one .md file per bullet (~2,643 rule files across 338 skills).

Scripts

The scripts/ directory contains executable helpers. Currently used primarily by tools/ category skills for installation.

Conventions

install.sh pattern

#!/bin/bash
set -e

# OS detection
detect_os() {
    case "$(uname -s)" in
        Linux*)                echo "linux" ;;
        Darwin*)               echo "macos" ;;
        MINGW*|MSYS*|CYGWIN*) echo "windows" ;;
        *)                     echo "unknown" ;;
    esac
}

OS=$(detect_os)
command_exists() { command -v "$1" >/dev/null 2>&1; }

# Install logic per OS...

# JSON output on stdout
echo "{\"status\":\"success\",\"tool\":\"my-tool\",\"os\":\"$OS\",\"version\":\"$VERSION\"}"

JSON output format

{
  "status": "success",
  "tool": "tool-name",
  "os": "linux",
  "action": "installed",
  "version": "1.2.3"
}

Parent/Child Skill Patterns

Parent (category) skills

Parent skills serve as navigation hubs. They contain:

• Overview of the domain
• Knowledge map (ASCII art or table showing all sub-skills)
• Sub-skill navigation table with USE FOR guidance per child
• High-level best practices for the domain

# Python

## Overview
Root skill for Python development...

## Sub-Skills

| Category | Skill | USE FOR |
|----------|-------|---------|
| Project System | project-system | pyproject.toml, build backends, PEP standards |
| Package Management | package-management | pip, uv, poetry, virtual environments |
| CLI | cli | argparse, click, typer, rich |
| Packages | packages/ | Individual library skills |

Leaf (terminal) skills

Leaf skills provide deep technical content on a specific topic:

• Detailed code examples (8-15 code blocks)
• API reference tables
• Comparison matrices for related tools
• Comprehensive Best Practices (5-15 items)
• Framework-specific integration patterns

Intermediate skills

Some skills both parent sub-skills AND provide their own content (e.g., typescript/packages/ lists all packages while also providing general TypeScript package guidance).

Quality & Compliance

Compliance scoring

Target: Medium-High or better for all skills.

Common pitfalls

• name not matching directory name (validation will catch this)
• compatibility as a YAML list instead of a string (must be claude, copilot, cursor not [claude, copilot, cursor])
• Code blocks without language tags (always use ```typescript, ```python, etc.)
• Missing USE FOR / DO NOT USE FOR in descriptions
• Best Practices section not being the last ## section (breaks rule extraction)
• Scope creep into sibling skill domains

Workflow

Creating a new skill

1. Create the directory under the appropriate category: skills/{category}/{skill-name}/
2. Author SKILL.md with frontmatter and body content:
   • Include name, description (with USE FOR / DO NOT USE FOR), license, metadata
   • Write body sections: Overview, core content, Best Practices (last section)
3. Generate rules: python scripts/generate-rules.py
4. Generate companion files: python scripts/generate-skill-files.py
5. Validate: agentskills validate skills/{category}/{skill-name}
6. Review that all files are present and well-formed

Modifying an existing skill

1. Edit SKILL.md as needed
2. Re-run generators if Best Practices or frontmatter changed:

   python scripts/generate-rules.py
   python scripts/generate-skill-files.py

3. Validate the modified skill

Regenerating all companion files

# Step 1: Generate rules/ directories from Best Practices sections
python scripts/generate-rules.py

# Step 2: Generate metadata.json, AGENTS.md, and README.md
python scripts/generate-skill-files.py

Validation

# Validate a single skill
agentskills validate skills/python/packages/fastapi

# Validate all skills
npm run validate

# Install the validator
pip install -r requirements.txt

The skills-ref validator checks:

• Frontmatter schema (required and optional fields, types)
• Naming conventions (lowercase, hyphens, length, directory match)
• File structure

Generator Scripts

Both scripts support --dry-run to preview without writing files.

generate-skill-files.py

Reads each SKILL.md, extracts frontmatter and body, then generates:

• metadata.json — flattened metadata from frontmatter
• AGENTS.md — body content without frontmatter
• README.md — structured human docs with sub-skill listing and rules/ count

generate-rules.py

Reads each SKILL.md body, finds ## Best Practices (or ## Guidelines, ## Rules, ## Recommendations), extracts bullet items, and generates:

• rules/_template.md — template for authoring new rules
• rules/_sections.md — index table of all rules with impact levels
• rules/{name}-{slug}.md — one file per bullet with YAML frontmatter (title, impact, tags)

Impact levels are assigned by keyword heuristics (see Impact levels table above).