AGENTS.md · trailofbits/skills

Sections

1. Resources
2. Technical Reference
3. Quality Standards
4. Before committing
5. Scripts a plugin ships
6. Working effectively in this repo

First lines (shown under the repo's CC-BY-SA-4.0 license)

# Contributing Skills

## Resources

**Official Anthropic documentation (always check these first):**

- [Claude Code Plugins](https://code.claude.com/docs/en/plugins)
- [Agent Skills](https://code.claude.com/docs/en/skills)
- [Best Practices](https://code.claude.com/docs/en/skills#best-practices)
- [Skill Authoring Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) — progressive disclosure, degrees of freedom, workflow checklists
- [The Complete Guide to Building Skills](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf) ([text](https://gist.github.com/liskl/269ae33835ab4bfdd6140f0beb909873)) — evaluation-driven development, iterative testing

**Reference skills** - learn by example at different complexity levels:

| Complexity | Skill | What It Demonstrates |
|------------|-------|---------------------|
| **Basic** | [git-cleanup](plugins/git-cleanup/) | Single self-contained SKILL.md, `allowed-tools` scoping |
| **Intermediate** | [constant-time-analysis](plugins/constant-time-analysis/) | Python package, references/, language-specific docs |
| **Advanced** | [culture-index](plugins/culture-index/) | Scripts, workflows/, templates/, PDF extraction, multiple entry points |

**When in doubt, copy one of these and adapt it.**

**Deep dives on skill authoring:**
- [Claude Skills Deep Dive](https://leehanchung.github.io/blogs/2025/10/26/claude-skills-deep-dive/) - Comprehensive analysis of skill architecture

**Example plugins worth studying:**
- [superpowers](https://github.com/obra/superpowers) - Advanced workflow patterns, TDD enforcement, multi-skill orchestration
- [compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin) - Production plugin structure
- [getsentry/skills](https://github.com/getsentry/skills) — Production Sentry skills; `security-review` is a standout routing + progressive disclosure example

**For Claude:** Use the `claude-code-guide` subagent for questions about official Claude
Code behaviour that you cannot answer from this repository — it has access to the
official documentation. For anything answerable by reading the files here, read them;
delegating a lookup you could do directly costs a round trip and buys nothing.

## Technical Reference

### Codex Compatibility

This repository uses Claude plugin marketplace metadata as the canonical source for Claude Code, Codex, and ChatGPT workspace imports. Codex supports `.claude-plugin/marketplace.json` and `plugins/<name>/.claude-plugin/plugin.json` directly, so do not add duplicate Codex-only sidecar metadata.

Rules:

- Do not add `.agents/plugins/marketplace.json`, `.codex/`, `.opencode/`, or
  `plugins/<name>/.codex-plugin/`. The validator enforces this — sidecars drift out of
  sync with the canonical metadata, which is why the last set was removed in #173.
- Keep plugin components at the plugin root using Codex-compatible default paths: `skills/`, `hooks/hooks.json`, `.mcp.json`, and `.app.json`.
- Skill interfaces in `skills/<skill>/agents/openai.yaml` use snake_case: when that optional file
  exists, `interface.display_name` and `interface.short_description` must both be
  non-empty strings. OpenAI documents these requirements and their error messages in
  [Skill agent metadata errors](https://developers.openai.com/plugins/deploy/submission-errors#skill-agent-metadata-errors).
  An icon-only file fails these requirements.
  `validate_skill_interfaces.py` checks these files in `make check`, pre-commit, and
  the Python tests job in `lint.yml`, which already installs PyYAML.
- Omit unknown optional author contacts instead of setting `email` or `url` to `""`.
- If a plugin needs MCP configuration, put it in `.mcp.json` at the plugin root rather than embedding an object in `.claude-plugin/plugin.json`.
- Both loadability checks run in CI, not in `make check` — they need the Claude Code
  and Codex CLIs installed, which is not a reasonable local prerequisite. Run them by
  hand if you are changing plugin metadata:

  ```sh
  python3 .github/scripts/check_claude_loadability.py
  python3 .github/scripts/check_codex_loadability.py
  ```

  If one fails, update the canonical Claude marketplace or the plugin root components
  so Codex can load them through Claude marketplace compatibility — do not add a
  sidecar to work around it.

### Plugin Structure

```
plugins/
  <plugin-name>/
    .claude-plugin/
      plugin.json         # Plugin metadata (name, version, description, author)
    commands/             # Optional: slash commands
    agents/               # Optional: autonomous agents
    workflows/            # Optional: dynamic workflows (*.js), ships as /<plugin>:<workflow>
    evals/                # Optional: `claude plugin eval` cases + graders
    skills/               # Optional: knowledge/guidance
      <skill-name>/
        SKILL.md          # Entry point with frontmatter
        references/       # Optional: detailed docs
        workflows/        # Optional: step-by-step guides (prose, not scripts)
        scripts/          # Optional: utility scripts
    hooks/                # Optional: event hooks
    tests/                # Optional: run_*.sh suites (CI runs these — keep them free)
    README.md             # Plugin documentation
```

**Important**: Component directories (`skills/`, `commands/`, `agents/`, `hooks/`) must be at the plugin root, NOT inside `.claude-plugin/`. Only `plugin.json` belongs in `.claude-plugin/`.

**Two different `workflows/`.** A **dynamic workflow** is a JavaScript file at the *plugin
root* under `workflows/`; it exports a `meta` object, orchestrates subagents in code, and
ships through the marketplace as `/<plugin-name>:<workflow-name>` (from `meta.name`, not the
filename). The older `skills/<skill>/workflows/` holds prose step-by-step guides. If a
SKILL.md has "Phase 1", "for each finding", or "repeat until" sections, the plan belongs in
a script at the plugin root, not in prose. See `plugins/variant-analysis/workflows/` for a
worked example, and note that `${CLAUDE_PLUGIN_ROOT}` is **not** available inside a workflow
script — it is not a hook, MCP, or LSP subprocess.

### Frontmatter

Skills and commands declare tools with `allowed-tools`, space-delimited:

```yaml
---
name: skill-name              # kebab-case, max 64 chars
description: "Third-person description of what it does and when to use it"
allowed-tools: Read Grep      # Optional: restrict to needed tools only
---
```

Agent files under `agents/` use a different key — `tools`, as a YAML list:

```yaml
---
name: agent-name
description: "What this agent does and when the coordinator should dispatch it"
tools:
  - Read
  - Grep
---
```

The keys are inverted between the two file types, and the loader silently ignores
the wrong one — the frontmatter still parses, the restriction simply does not apply
and the agent inherits everything. The validator checks this.

### Naming Conventions

- **kebab-case**: `constant-time-analysis`, not `constantTimeAnalysis`
- **Gerund form preferred**: `analyzing-contracts`, `processing-pdfs` (not `contract-analyzer`, `pdf-processor`)
- **Avoid vague names**: `helper`, `utils`, `tools`, `misc`
- **Avoid reserved words**: `anthropic`, `claude`

### Path Handling

- Use `{baseDir}` for paths, **never hardcode** absolute paths
- Use forward slashes (`/`) even on Windows

### Python Scripts

When skills include Python scripts with dependencies:

1. **Use PEP 723 inline metadata** - Declare dependencies in the script header:
   ```python
   # /// script
   # requires-python = ">=3.11"
   # dependencies = ["requests>=2.28", "pydantic>=2.0"]
   # ///
   ```

2. **Use `uv run`** - Enables automatic dependency resolution:
   ```bash
   uv run {baseDir}/scripts/process.py input.pdf
   ```

3. **Include `pyproject.toml`** - Keep in `scripts/` for development tooling (ruff, etc.)