# agents-md

Adopt this skill: https://proskills.md/skills/other/getsentry-skills-skills-agents-md

Page: https://proskills.md/skills/other/getsentry-skills-skills-agents-md
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/agents-md/SKILL.md
size: 3188
sha: bd92e4a9df47f63bd943bc3d5011da0b3d6e04ff
upstream: https://github.com/getsentry/skills/blob/main/skills/agents-md/SKILL.md

`````text
---
name: agents-md
description: Creates and maintains concise AGENTS.md and CLAUDE.md project instruction files. Use when asked to create AGENTS.md, update AGENTS.md, maintain agent docs, set up CLAUDE.md, document repository agent conventions, or keep coding-agent instructions minimal and reference-backed.
---

# Maintaining AGENTS.md

Goal: concise, actionable agent instructions. Target under 60 lines; never exceed 100.

## Workflow

1. Inspect before writing:
   - package manager: lock files and manifests
   - commands: `package.json`, `Makefile`, task runners, CI workflows
   - docs/specs/policies: `README.md`, `CONTRIBUTING.md`, `docs/`, `specs/`, `policies/`, `SECURITY.md`, `.github/`
   - conventions: current code patterns, test layout, generated files, legacy areas to avoid
2. Choose scope:
   - root `AGENTS.md`: repo-wide defaults
   - nested `AGENTS.md`: only when a subtree has different commands or rules
   - closest instruction file wins; keep narrower files shorter than root files
3. Write the smallest useful file.
4. Verify exact paths and commands exist.

## File Setup

- Create `AGENTS.md` at the repository root.
- If a Claude-compatible entrypoint is required, symlink `CLAUDE.md` to `AGENTS.md`.
- Do not maintain divergent `AGENTS.md` and `CLAUDE.md` copies.

## Default Sections

Use only sections that add non-obvious value.

````markdown
# Agent Instructions

## Package Manager
- Use **pnpm**: `pnpm install`

## Commands
| Task | Command |
|------|---------|
| Test file | `pnpm vitest run path/to/file.test.ts` |
| Lint file | `pnpm eslint path/to/file.ts` |

## External References
| Need | File |
|------|------|
| Setup | `CONTRIBUTING.md` |
| Architecture | `docs/architecture.md` |
| Security policy | `SECURITY.md` |

## Key Conventions
- Generated files: update with `pnpm generate`; do not edit by hand.

## Commit Attribution
AI commits MUST include:
```
Co-Authored-By: (the agent's name and attribution byline)
```
````

## Writing Rules

- Use headings, bullets, and tables; avoid paragraphs.
- Use repo-relative paths; avoid vague references like "see docs".
- Reference existing docs/specs/policies instead of copying them.
- List exact external files for setup, architecture, API specs, security, release, and policy docs when they exist.
- Prefer file-scoped test/lint/typecheck commands; include full builds only when no narrower command exists.
- Put commands in tables when there is more than one.
- Keep one rule per bullet.
- Keep rationale out unless it prevents a likely mistake.
- Do not restate linter, formatter, or typechecker config.
- Do not list installed skills or plugins.
- Do not include generic quality slogans.

## External Reference Rules

Good:

```markdown
## External References
| Need | File |
|------|------|
| API contract | `docs/api.md` |
| Release process | `docs/releasing.md` |
```

## Anti-Patterns

- welcome text, intros, conclusions, or pleasantries
- long prose explaining why instructions matter
- duplicated content from `README.md`, `CONTRIBUTING.md`, or policy docs
- project-wide commands when file-scoped commands are available
- nested `AGENTS.md` files that repeat root instructions
`````

## File: skills/agents-md/SOURCES.md
size: 4307
sha: edfafb63491741c75f1291334cd4b92c57eb0b12
upstream: https://github.com/getsentry/skills/blob/main/skills/agents-md/SOURCES.md

```text
# Sources

This file tracks material synthesized into `agents-md`.

## Selected profile

- `skills/skill-writer/references/examples/workflow-process-skill.md`

Why: this skill is a repeatable authoring workflow with pre-inspection, scoped output, validation, and failure controls.

## Current source inventory

| Source | Type | Trust tier | Retrieved | Confidence | Contribution | Usage constraints | Notes |
|---|---|---|---|---|---|---|---|
| `AGENTS.md` | repo policy | canonical | 2026-05-04 | high | Requires `skill-writer`, concise prose, exact registration expectations | local repository authority | Highest-priority local instruction source |
| `README.md` | repo policy | canonical | 2026-05-04 | high | Skill layout, `SPEC.md` convention, public inventory style | local repository authority | Confirms canonical `skills/` tree |
| `CONTRIBUTING.md` | repo policy | canonical | 2026-05-04 | high | Local testing and contribution workflow | local repository authority | Used for validation expectations |
| `skills/skill-writer/SKILL.md` and references | local canonical | canonical | 2026-05-04 | high | Skill update workflow, source capture, authoring, validation | local repository authority | Primary authoring workflow |
| `https://agents.md/` | official format guide | canonical | 2026-05-04 | high | AGENTS.md purpose, common sections, nested files, closest-file precedence | public format guidance | Supports path-backed and scoped instructions |
| `https://developers.openai.com/codex/guides/agents-md` | official product docs | canonical | 2026-05-04 | high | Codex discovery order, global/project scopes, nested precedence, size cap, verification commands | OpenAI-specific behavior | Used only for compatibility guidance |
| `https://agentskills.io/specification` | official spec | canonical | 2026-05-04 | high | Skill frontmatter, progressive disclosure, focused references | skill format guidance | Supports concise runtime file shape |

## Decisions

1. Make external file enumeration a default AGENTS.md section when docs/specs/policies exist.
   Status: adopted
   Why: AGENTS.md should point agents to exact source files instead of copying policy or asking them to scan vague directories.

2. Prefer concise root files plus nested overrides.
   Status: adopted
   Why: official AGENTS.md and Codex docs both describe hierarchical instructions where narrower files override broader guidance.

3. Keep `CLAUDE.md` as a compatibility symlink when needed.
   Status: adopted
   Why: one canonical instruction file avoids divergent provider-specific copies.

4. Treat OpenAI `AGENTS.override.md` behavior as compatibility guidance, not a shared-repo default.
   Status: adopted
   Why: it is useful for Codex-specific overrides but can surprise other tools and humans if used as the main repo contract.

5. Cut prose and examples to a compact template.
   Status: adopted
   Why: instruction-following and truncation risks grow with long agent docs; the user explicitly requested minimal prose.

## Coverage matrix

| Dimension | Coverage status | Evidence |
|---|---|---|
| Repo inspection before writing | complete | local repo policy, `skill-writer` workflow |
| External docs/specs/policies enumeration | complete | user concern, AGENTS.md format guidance |
| Nested scope and precedence | complete | official AGENTS.md guide, OpenAI Codex docs |
| Prose minimization | complete | user concern, Agent Skills progressive disclosure |
| Command precision | complete | AGENTS.md examples, repo contribution conventions |
| CLAUDE.md compatibility | complete | existing skill behavior, local repo convention |
| Provider-specific variance | partial | OpenAI Codex docs covered; other tools deferred until a concrete repo need |

## Open gaps

1. Add provider-specific discovery notes only when a concrete repository or tool requires them.
2. Add durable before/after examples only if future changes regress into long prose or vague references.

## Stopping rationale

Further retrieval is currently low-yield. The source pack covers local repo policy, the official AGENTS.md format guide, OpenAI Codex discovery behavior, and the Agent Skills specification.

## Changelog

- 2026-05-04: Added source-backed external reference guidance, nested-scope rules, `SPEC.md`, and provenance.
```

## File: skills/agents-md/SPEC.md
size: 4160
sha: c699def49233fbb1c6a43ebadf74af8e8993c522
upstream: https://github.com/getsentry/skills/blob/main/skills/agents-md/SPEC.md

```text
# AGENTS.md Specification

## Intent

`agents-md` creates and maintains compact repository instruction files for coding agents.

It should turn scattered repo norms into a short `AGENTS.md` index: commands, non-obvious conventions, and exact links to existing docs/specs/policies.

## Scope

In scope:

- Root `AGENTS.md` files.
- Nested `AGENTS.md` files for subtree-specific overrides.
- `CLAUDE.md` compatibility symlinks when needed.
- Concise command tables, external reference tables, and commit attribution rules.
- Removing duplicated prose from existing agent docs.

Out of scope:

- Rewriting the referenced docs themselves.
- Replacing `README.md`, `CONTRIBUTING.md`, policy docs, or architecture docs.
- Listing installed skills/plugins.
- Encoding linter or formatter rules already enforced by config.
- Maintaining divergent tool-specific copies of the same instructions.

## Users And Trigger Context

- Primary users: engineers and agents maintaining repository-level agent instructions.
- Should trigger for: create AGENTS.md, update AGENTS.md, maintain agent docs, set up CLAUDE.md, document repo agent conventions, reduce agent instruction prose.
- Should not trigger for: general docs writing, PR descriptions, code review, or creating reusable agent skills.

## Runtime Contract

- Inspect repo commands, configs, docs, specs, and policies before writing.
- Prefer exact repo-relative paths and command tables.
- Enumerate external files for setup, architecture, API specs, security, release, and policy docs when present.
- Keep root guidance broad and nested guidance narrow.
- Keep `AGENTS.md` under 60 lines when practical and under 100 lines always.
- Preserve the commit attribution section when the repo requires AI co-authorship.
- Use a `CLAUDE.md` symlink only for compatibility; avoid divergent copies.

## Source And Evidence Model

Authoritative sources:

- Repository instructions, especially root `AGENTS.md`.
- `README.md`, `CONTRIBUTING.md`, package manifests, CI workflows, and settings files.
- Existing project docs, specs, security docs, and policy files.
- Official AGENTS.md format guidance and OpenAI Codex discovery behavior.

Useful improvement sources:

- Repositories with concise, path-backed agent docs.
- Review feedback about stale commands, duplicated docs, or overlong instructions.
- Agent failures caused by missing exact file paths, command ambiguity, or nested instruction conflicts.

Do not store secrets, private customer data, or long copied policy text in examples.

## Reference Architecture

- `SKILL.md` contains the runtime checklist, template, and anti-patterns.
- `SPEC.md` contains this maintenance contract.
- `SOURCES.md` stores provenance, decisions, coverage, and gaps.
- `references/`, `scripts/`, and `assets/` are unused until repeated failures require focused lookup material.

## Evaluation

- Lightweight validation: check the generated file for line count, exact commands, exact external paths, no duplicated policy prose, and no vague "see docs" references.
- Trigger QA: verify create/update/CLAUDE.md requests trigger this skill, while generic docs and skill-authoring tasks do not.
- Holdout examples: one simple single-package repo, one monorepo with nested overrides, one repo with existing docs/specs/policies to enumerate.
- Acceptance gates: the resulting `AGENTS.md` is short, command-backed, path-backed, and free of redundant style rules.

## Known Limitations

- The skill relies on local file inspection; it cannot know private policy docs that are not present or supplied.
- Some agent tools have provider-specific discovery behavior; keep compatibility notes concise and avoid making one provider the default.
- Very large monorepos may need several nested files instead of a longer root file.

## Maintenance Notes

- Update `SKILL.md` when runtime sections, templates, or anti-patterns change.
- Update `SPEC.md` when scope, evaluation, or evidence policy changes.
- Update `SOURCES.md` when AGENTS.md discovery behavior or source-backed decisions change.
- Add focused references only when repeated failures cannot be fixed with the compact runtime checklist.
```

## File: README.md
upstream: https://github.com/getsentry/skills/blob/main/README.md

````text
# Sentry Skills

> [!NOTE]
> For skills to help set up Sentry in your project or debug production issues, see https://github.com/getsentry/sentry-for-ai

Agent skills for Sentry employees, following the [Agent Skills](https://agentskills.io) open format.

## Installation

### Claude Code

```bash
claude plugin marketplace add getsentry/skills
claude plugin install sentry-skills@sentry-skills
```

If you use `claude plugin marketplace add --sparse` for this repo, include `skills` and `agents` alongside `.claude-plugin` because the root plugin manifest loads repo-root `skills/` and `agents/`.

Restart Claude Code after installation. Skills activate automatically when relevant.

**Update:**

```bash
claude plugin marketplace update
claude plugin update sentry-skills@sentry-skills
```

Or run `/plugin` to open the plugin manager.

### Skills Package (skills.sh)

For agents supporting the [skills.sh](https://skills.sh) ecosystem:

```bash
npx skills add getsentry/skills
```

Works with Claude Code, Cursor, Cline, GitHub Copilot, and other compatible agents.

## Available Skills

| Skill | Description |
|-------|-------------|
| [agents-md](skills/agents-md/SKILL.md) | Create and maintain concise, reference-backed AGENTS.md and CLAUDE.md files. |
| [blog-writing-guide](skills/blog-writing-guide/SKILL.md) | Write, review, and improve blog posts for the Sentry engineering blog following Sentry's specific writing standards, voice, and quality bar. |
| [brand-guidelines](skills/brand-guidelines/SKILL.md) | Write copy following Sentry brand guidelines. |
| [browse-local-sentry](skills/browse-local-sentry/SKILL.md) | Connect an agent's browser to a local Sentry dev server, trusted and signed in, to QA and screenshot the real product. |
| [claude-settings-audit](skills/claude-settings-audit/SKILL.md) | Analyze a repository to generate recommended Claude Code settings.json permissions. |
| [code-review](skills/code-review/SKILL.md) | Perform code reviews following Sentry engineering practices. |
| [code-simplifier](skills/code-simplifier/SKILL.md) | Simplifies and refines code for clarity, consistency, and maintainability while preserving all functionality. |
| [commit](skills/commit/SKILL.md) | ALWAYS use this skill when committing code changes — never commit directly without it. |
| [create-branch](skills/create-branch/SKILL.md) | Create git branches following Sentry naming conventions. |
| [django-access-review](skills/django-access-review/SKILL.md) | Django access control and IDOR security review. |
| [django-perf-review](skills/django-perf-review/SKILL.md) | Django performance code review. |
| [doc-coauthoring](skills/doc-coauthoring/SKILL.md) | Guide users through a structured workflow for co-authoring documentation. |
| [document-api-endpoint](skills/document-api-endpoint/SKILL.md) | Document and type a Sentry API endpoint with drf-spectacular OpenAPI schema — write/fix `@extend_schema`, specify response TypedDicts, type parameters, fix type drift, and promote to PUBLIC. |
| [find-bugs](skills/find-bugs/SKILL.md) | Find bugs, security vulnerabilities, and code quality issues in local branch changes. |
| [gh-review-requests](skills/gh-review-requests/SKILL.md) | Fetch unread GitHub notifications for open PRs where review is requested from a specified team or opened by a team member. |
| [gha-security-review](skills/gha-security-review/SKILL.md) | GitHub Actions security review for workflow exploitation vulnerabilities. |
| [iterate-pr](skills/iterate-pr/SKILL.md) | Iterate on a PR until CI passes and actionable review feedback is addressed. |
| [presentation-creator](skills/presentation-creator/SKILL.md) | Create data-driven presentation slides using React, Vite, and Recharts with Sentry branding. |
| [pr-link-issue](skills/pr-link-issue/SKILL.md) | Append a GitHub issue link and its Linear ticket to the current PR's description. |
| [pr-screenshots](skills/pr-screenshots/SKILL.md) | Capture real-product UI screenshots, lay them out as before/after tables in PR descriptions, and upload them with `gh --attach`. |
| [pr-writer](skills/pr-writer/SKILL.md) | Create, refresh, and rewrite pull request titles and descriptions following Sentry conventions. |
| [prompt-optimizer](skills/prompt-optimizer/SKILL.md) | Optimize prompts with evals, model-family adapters, and exact external context references. |
| [secret-serialization](skills/secret-serialization/SKILL.md) | Find secrets and tokens that leak through generated serialization such as dataclass repr, asdict, model_dump, JSON.stringify, logs, and tracing spans. |
| [security-model](skills/security-model/SKILL.md) | Define and maintain SECURITY_MODEL.md files that tell security review tools a repository's trust boundaries, invariants, reportable finding classes, and exclusions. |
| [security-review](skills/security-review/SKILL.md) | Security code review for vulnerabilities. |
| [skill-scanner](skills/skill-scanner/SKILL.md) | Scan agent skills for security issues. |
| [skill-writer](skills/skill-writer/SKILL.md) | Canonical workflow to synthesize, create, and iteratively improve agent skills for this repository. |
| [sred-project-organizer](skills/sred-project-organizer/SKILL.md) | Take a list of projects and their related documentation, and organize them into the SRED format for submission. |
| [sred-work-summary](skills/sred-work-summary/SKILL.md) | Go back through the previous year of work and create a Notion doc that groups relevant links into projects that can then be documented as SRED projects. |
| [triage-frontend-issues](skills/triage-frontend-issues/SKILL.md) | Triage the Sentry `javascript` project queue by archiving non-actionable noise (third-party libs, browser quirks, transient 5xx, test traffic) with `untilEscalating` after user approval. |
| [typing-exclusion-worker](skills/typing-exclusion-worker/SKILL.md) | Python typing exclusion worker: remove assigned mypy exclusion modules in small scoped batches, fix typing issues, run validation, and produce a structured completion summary. |

## Available Subagents

| Subagent | Description |
|----------|-------------|
| [code-simplifier](agents/code-simplifier.md) | Simplifies and refines code for clarity, consistency, and maintainability while preserving all functionality |
| [senpai](agents/senpai.md) | Senior engineer and technical mentor for new Sentry hires. Explains infrastructure, architecture, and engineering concepts step-by-step with references |

## Contributing

### Local Development

```bash
git clone git@github.com:getsentry/skills.git ~/sentry-skills
claude plugin marketplace add ~/sentry-skills
claude plugin install sentry-skills
```

If you use `claude plugin marketplace add --sparse` for this repo, include `skills` and `agents` alongside `.claude-plugin` because the root plugin manifest loads repo-root `skills/` and `agents/`.

### Repository Structure

```
sentry-skills/
├── .claude-plugin/
│   ├── marketplace.json      # Marketplace manifest
│   └── plugin.json           # Root plugin manifest for sentry-skills
├── .agents/
│   └── skills -> ../skills   # Local mirror for agent tooling
├── agents/
│   ├── code-simplifier.md
│   └── senpai.md
├── skills/
│   ├── code-review/
│   │   └── SKILL.md
│   └── commit/
│       └── SKILL.md
├── AGENTS.md                 # Agent-facing documentation
├── CLAUDE.md                 # Symlink to AGENTS.md
└── README.md                 # This file
```

The canonical skill source for the `sentry-skills` plugin lives at repo-root `skills/`.
`.agents/skills` mirrors that tree for local agent tooling, and the root plugin manifest loads repo-root `skills/` and `agents/`.

New skills and materially changed skills should include a root-level `SPEC.md` alongside `SKILL.md`.

### Creating New Skills

Skills follow the [Agent Skills specification](https://agentskills.io/specification). Each skill requires a `SKILL.md` file with YAML frontmatter.

For repeatable `skill-writer` evaluation prompts, see [ski
````
