agent-skills

# AGENTS.md

This file provides guidance to AI coding agents when working with this repository.

## Repository Overview

A collection of skills for AI coding agents (Claude Code, Cursor, etc.). Skills are packaged instructions and scripts that extend agent capabilities and follow the [Agent Skills specification](https://agentskills.io/).

## Repository Structure

```
agent-skills/
├── skills/              # Individual skill directories
│   └── gemini-cli/     # Gemini CLI skill
│       ├── SKILL.md    # Skill definition and instructions
│       └── scripts/    # Helper scripts
├── README.md           # User-facing documentation
└── AGENTS.md          # This file - instructions for AI agents
```

## Creating a New Skill

### Directory Structure

```
skills/
  {skill-name}/           # kebab-case directory name
    SKILL.md              # Required: skill definition
    scripts/              # Optional: executable scripts
    references/           # Optional: additional documentation
    assets/              # Optional: templates, images, data
```

### Naming Conventions

- **Skill directory**: `kebab-case` (e.g., `gemini-cli`, `pdf-tools`)
- **SKILL.md**: Always uppercase, always this exact filename
- **Scripts**: Descriptive names with appropriate extensions (`.sh`, `.mjs`, `.py`)

### SKILL.md Format

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

```markdown
---
name: skill-name
description: Clear description of what this skill does and when to use it. Include trigger phrases.
license: Apache-2.0  # Optional
metadata:            # Optional
  author: your-name
  version: "1.0"
---

# Skill Title

Brief description of what the skill does.

## When To Use

Use this skill when:
- Specific condition or trigger phrase
- User asks to do X
- Working with Y technology

## How It Works

1. Step-by-step explanation
2. Of the skill's workflow
3. And what it does

## Usage

If the skill includes scripts:

```bash
node scripts/example.mjs --arg value
```

**Arguments:**
- `--arg` - Description (optional, defaults to X)

**Examples:**

```bash
# Example 1: Basic usage
node scripts/example.mjs --prompt "Do something"

# Example 2: Advanced usage
node scripts/example.mjs --prompt "..." --option value
```

## Output

Example of what the user will see:

```
Expected output format
```

## Guidelines

- Important guideline 1
- Best practice 2
- Safety rule 3

## Troubleshooting

- **Issue**: Solution
```

### Required Frontmatter Fields

- `name`: Must be 1-64 characters, lowercase letters/numbers/hyphens only, no leading/trailing hyphens, must match directory name
- `description`: Must be 1-1024 characters, describe what the skill does and when to use it

### Optional Frontmatter Fields

- `license`: License name or reference (e.g., "Apache-2.0", "MIT", "Proprietary")
- `compatibility`: Environment requirements (e.g., "Requires Node.js 18+")
- `metadata`: Arbitrary key-value pairs for additional info

### Best Practices for Context Efficiency

Skills are loaded on-demand to minimize context usage:

1. **Metadata** (~100 tokens): Only name/description loaded at startup
2. **Instructions** (<5000 tokens): Full SKILL.md loaded when skill activates
3. **Resources** (as needed): Scripts/references loaded only when required

**Keep SKILL.md under 500 lines** - move detailed documentation to `references/` directory.

**Write specific descriptions** with trigger phrases so agents know when to activate.

**Use progressive disclosure** - reference supporting files that load only when needed.

**Prefer scripts over inline code** - script execution doesn't consume context (only output does).

### Script Requirements

When including executable scripts:

- Use appropriate shebang (`#!/bin/bash`, `#!/usr/bin/env node`, etc.)
- For bash: Use `set -e` for fail-fast behavior
- Write status messages to stderr: `echo "Message" >&2`
- Write machine-readable output (JSON) to stdout
- Include error handling with helpful messages
- Document all arguments with defaults and examples
- Reference the script with relative paths from skill root

### File References

Reference other files using relative paths from the skill root:

```markdown
See [detailed guide](references/GUIDE.md) for more information.

Run the script:
bash scripts/deploy.sh
```

Keep references one level deep - avoid deeply nested reference chains.

## Validation

Validate your skill format using the reference implementation:

```bash
npm install -g @agentskills/skills-ref
skills-ref validate ./skills/your-skill-name
```

## Adding a New Skill Workflow

When creating a new skill:

1. Create directory: `mkdir skills/new-skill-name`
2. Create SKILL.md with required frontmatter
3. Add scripts directory if needed: `mkdir skills/new-skill-name/scripts`
4. Write clear instructions with examples
5. Validate the skill format
6. Test the skill with an agent
7. Update README.md to list the new skill

## Testing Skills

Before committing:

1. Validate YAML frontmatter is correct
2. Verify all relative file paths work
3. Test scripts execute correctly
4. Confirm trigger phrases are specific enough
5. Check that SKILL.md is under 500 lines

## Code Style

- Use clear, descriptive variable names
- Include error handling
- Add comments for complex logic
- Follow language-specific conventions
- Keep scripts focused on single responsibility