Daniel Tomlinson
a4933e7579
Establishes standards for creating and organizing AI agent skills in AGENTS.md and provides a reference implementation for performing technical and visual website design audits.
119 lines
4.2 KiB
Markdown
119 lines
4.2 KiB
Markdown
# 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
|
|
|
|
```markdown
|
|
---
|
|
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):**
|
|
```bash
|
|
# Install a specific skill
|
|
skills install {skill-name}
|
|
```
|
|
|
|
**Claude Code (manual):**
|
|
```bash
|
|
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`.
|