semgrep__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.ai and Claude Code for working with code security. Skills are packaged instructions that extend Claude's capabilities.

## Skill Types in This Repo

### Guideline Skills (code-security, llm-security)
Security guidelines with categorized rules. Structure:
```
{skill-name}/
├── SKILL.md           # Skill definition
├── rules/             # Individual rule files
│   ├── _sections.md   # Index of categories
│   └── *.md           # Rule files
├── AGENTS.md          # Generated from rules (via make build)
└── README.md
```

### Reference Skills (semgrep)
Tool-focused skills with documentation. Structure:
```
{skill-name}/
├── SKILL.md           # Skill definition
├── references/        # Supporting documentation
│   └── *.md           # Detailed guides
└── README.md
```

## Creating a New Skill

### Directory Structure

```
skills/
  {skill-name}/           # kebab-case directory name
    SKILL.md              # Required: skill definition
    rules/                # Optional: for guideline-based skills
    references/           # Optional: for reference documentation
    scripts/              # Optional: for executable scripts
  {skill-name}.zip        # Generated by make zip
```

### Naming Conventions

- **Skill directory**: `kebab-case` (e.g., `code-security`, `semgrep`)
- **SKILL.md**: Always uppercase, always this exact filename
- **Zip file**: Must match directory name exactly: `{skill-name}.zip`

### SKILL.md Format

```markdown
---
name: {skill-name}
description: {One sentence describing when to use this skill. Include trigger phrases.}
---

# {Skill Title}

{Brief description of what the skill does.}

## When to Use

{Describe ideal scenarios and when NOT to use}

## Usage / Categories / Quick Reference

{Main content - varies by skill type}

## References

{Links to detailed documentation in references/ folder if applicable}
```

### 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
- **File references work one level deep** — link directly from SKILL.md to supporting files

## Build System

### Makefile Targets

```bash
make install     # Install pnpm dependencies
make validate    # Validate all skills with rules/ directories
make build       # Build AGENTS.md for skills with rules/
make zip         # Create zip packages for all skills
make             # All of the above (validate, build, zip)
make clean       # Remove generated files
```

### Single Skill Operations

```bash
make validate-skill SKILL=code-security
make build-skill SKILL=llm-security
```

### What Gets Built

- **Skills with `rules/`**: Runs validation, builds `AGENTS.md`, extracts test cases, creates zip
- **Skills without `rules/`**: Only creates zip (no validation/build needed)

### Before Committing

**Always run `make` before committing and pushing changes.** This ensures:
- All skills are validated
- Generated files (AGENTS.md, zip packages) are up to date
- Tests pass

```bash
make && git add -A && git commit -m "message" && git push
```

## End-User Installation

Document this installation method for users:

```bash
npx skills add semgrep/skills
```

For manual installation:

**Claude Code:**
```bash
cp -r skills/{skill-name} ~/.claude/skills/
```

**claude.ai:**
Add the skill to project knowledge or paste SKILL.md contents into the conversation.

## Adding Rules to Guideline Skills

For skills with `rules/` directories (code-security, llm-security):

1. Copy `rules/_template.md` to `rules/{category}.md`
2. Follow the frontmatter format:
   ```markdown
   ---
   title: Rule Title
   impact: HIGH
   tags: security, category-name
   ---
   ```
3. Include **Incorrect** and **Correct** code examples
4. Run `make validate` to check formatting
5. Run `make` to rebuild everything