llm-skills/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 skills for Claude Code and Claude.ai. Skills are packaged instructions and optional scripts that extend Claude's capabilities.

Skill Authoring Best Practices

When creating or modifying skills, refer to the official best practices documentation:

https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

Key principles:

• Be concise — Claude is already smart, only add context it doesn't have
• Set appropriate degrees of freedom for the task's fragility
• Test with the models you plan to use

Creating a New Skill

Directory Structure

{skill-name}/               # kebab-case directory name
  SKILL.md                   # Required: skill definition with YAML frontmatter
  scripts/                   # Optional: executable scripts
    {script-name}.sh         # Bash scripts (preferred)
    {script-name}.py         # Python scripts
  {supporting-files}.md      # Optional: reference docs, templates, examples

Naming Conventions

• Skill directory: kebab-case (e.g., audit-website-design, code-review)
• SKILL.md: Always uppercase, always this exact filename
• Scripts: kebab-case.sh or kebab-case.py (e.g., deploy.sh, analyze.py)

SKILL.md Format

---
name: {skill-name}
description: {One or two sentences describing what the skill does AND when to use it. Include trigger phrases. Max 1024 characters.}
---

# {Skill Title}

{Brief description of what the skill does.}

## How It Works / Workflow

{Numbered list or sections explaining the skill's workflow}

## Usage

{Show common usage patterns and examples}

## Output

{Describe or show example output}

Required frontmatter fields:

Field	Requirements
name	Max 64 chars, lowercase letters/numbers/hyphens only
description	Non-empty, max 1024 chars, third-person voice ("Extracts..." not "I extract...")

Optional frontmatter fields:

Field	Description
disable-model-invocation	true to prevent Claude auto-triggering (manual /name only)
user-invocable	false to hide from / menu (background knowledge only)
allowed-tools	Space-separated tools pre-approved when skill is active
argument-hint	Hint shown in autocomplete, e.g. [url] or [filename]
effort	Reasoning effort: low, medium, high, max
context	Set to fork to run in a subagent
agent	Subagent type when context: fork (e.g., Explore, Plan)
model	Model override when skill is active
paths	Glob patterns limiting when skill activates

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. To minimize context usage:

• Keep SKILL.md under 500 lines — put detailed reference material in separate files
• Write specific descriptions — helps the agent know exactly when to activate the skill
• Use progressive disclosure — reference supporting files that get read only when needed
• Prefer scripts over inline code — script execution doesn't consume context (only output does)
• File references should be one level deep — link directly from SKILL.md to supporting files, avoid chains of references

Script Best Practices

• Use #!/bin/bash shebang and set -e for fail-fast behavior
• Write status messages to stderr: echo "Message" >&2
• Write machine-readable output (JSON) to stdout where applicable
• Include a cleanup trap for temp files
• Handle errors explicitly rather than letting Claude figure them out
• Document all constants (no "magic numbers")

End-User Installation

Claude Code (via skills.sh):

# Install a specific skill
skills install {skill-name}

Claude Code (manual):

cp -r {skill-name} ~/.claude/skills/

Claude.ai: Add the skill zip to project knowledge or paste SKILL.md contents into the conversation. If the skill requires network access, add required domains at claude.ai/settings/capabilities.