⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
agents-md
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.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
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 open format.
Installation
Claude Code
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:
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 ecosystem:
npx skills add getsentry/skills
Works with Claude Code, Cursor, Cline, GitHub Copilot, and other compatible agents.
Available Skills
| Skill | Description |
|---|---|
| agents-md | Create and maintain concise, reference-backed AGENTS.md and CLAUDE.md files. |
| blog-writing-guide | Write, review, and improve blog posts for the Sentry engineering blog following Sentry's specific writing standards, voice, and quality bar. |
| brand-guidelines | Write copy following Sentry brand guidelines. |
| browse-local-sentry | 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 | Analyze a repository to generate recommended Claude Code settings.json permissions. |
| code-review | Perform code reviews following Sentry engineering practices. |
| code-simplifier | Simplifies and refines code for clarity, consistency, and maintainability while preserving all functionality. |
| commit | ALWAYS use this skill when committing code changes — never commit directly without it. |
| create-branch | Create git branches following Sentry naming conventions. |
| django-access-review | Django access control and IDOR security review. |
| django-perf-review | Django performance code review. |
| doc-coauthoring | Guide users through a structured workflow for co-authoring documentation. |
| document-api-endpoint | 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 | Find bugs, security vulnerabilities, and code quality issues in local branch changes. |
| gh-review-requests | Fetch unread GitHub notifications for open PRs where review is requested from a specified team or opened by a team member. |
| gha-security-review | GitHub Actions security review for workflow exploitation vulnerabilities. |
| iterate-pr | Iterate on a PR until CI passes and actionable review feedback is addressed. |
| presentation-creator | Create data-driven presentation slides using React, Vite, and Recharts with Sentry branding. |
| pr-link-issue | Append a GitHub issue link and its Linear ticket to the current PR's description. |
| pr-screenshots | Capture real-product UI screenshots, lay them out as before/after tables in PR descriptions, and upload them with gh --attach. |
| pr-writer | Create, refresh, and rewrite pull request titles and descriptions following Sentry conventions. |
| prompt-optimizer | Optimize prompts with evals, model-family adapters, and exact external context references. |
| secret-serialization | Find secrets and tokens that leak through generated serialization such as dataclass repr, asdict, model_dump, JSON.stringify, logs, and tracing spans. |
| security-model | 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 | Security code review for vulnerabilities. |
| skill-scanner | Scan agent skills for security issues. |
| skill-writer | Canonical workflow to synthesize, create, and iteratively improve agent skills for this repository. |
| sred-project-organizer | Take a list of projects and their related documentation, and organize them into the SRED format for submission. |
| sred-work-summary | 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 | 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 | 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 | Simplifies and refines code for clarity, consistency, and maintainability while preserving all functionality |
| senpai | Senior engineer and technical mentor for new Sentry hires. Explains infrastructure, architecture, and engineering concepts step-by-step with references |
Contributing
Local Development
git clone [email protected]: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. Each skill requires a SKILL.md file with YAML frontmatter.
For repeatable skill-writer evaluation prompts, see [ski
// HOW IT'S BUILT
// FILES
4 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
skills/agents-md/SKILL.md3.1 KBbd92e4a9df47upstream ↗
--- 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 instructionsskills/agents-md/SOURCES.md4.2 KBedfafb634917upstream ↗
# 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.skills/agents-md/SPEC.md4.1 KBc699def49233upstream ↗
# 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.README.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/getsentry-skills-skills-agents-md.md