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

---
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

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

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

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

End-User Installation

Document this installation method for users:

npx skills add semgrep/skills

For manual installation:

Claude Code:

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:

   ---
   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