AGENTS.md · getsentry/skills

Sections

1. Skill Structure
2. Creating/Updating Skills
3. Key Conventions
4. References

First lines (shown under the repo's Apache-2.0 license)

# Agent Instructions

## Skill Structure
```
skills/<skill-name>/SKILL.md
skills/<skill-name>/SPEC.md
```

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

## Creating/Updating Skills
ALWAYS use `/skill-writer` — it handles requirements, writing, registration, and validation.

- Do **not** create per-skill alias or symlink skills
- The repo-level `.agents/skills` path is a convenience mirror of canonical `skills/`
- List only canonical skills in public skill inventories (for example `pr-writer`, `skill-writer`)

### Registration Checklist
1. Create `skills/<skill-name>/SKILL.md`
2. Create `skills/<skill-name>/SPEC.md`
3. Add to `README.md` Available Skills table (alphabetical by canonical skill name; exclude aliases/symlinks)
4. Add to `.claude/settings.json`: `Skill(sentry-skills:<skill-name>)`
5. Add to allowlist in `skills/claude-settings-audit/SKILL.md`
6. For skills with deliberate invocation policy, set Claude's `disable-model-invocation` in `SKILL.md` and Codex's `policy.allow_implicit_invocation` in `agents/openai.yaml` to matching behavior

## Key Conventions
- Frontmatter `---` must be the **first line** of SKILL.md — no comments before it
- `name` field must match the directory name exactly
- `description` includes trigger keywords — this is how agents discover the skill
- Attribution comments go **after** the closing `---`
- Python scripts: always use `uv run <script>`, never `python` or `python3`
- Keep SKILL.md under 500 lines; move reference material to `references/`
- Keep runtime instructions in `SKILL.md`; put intent, source/evidence model, evaluation, limitations, and maintenance rules in `SPEC.md`

## References
- Skill template and optional fields: `README.md`
- Testing and PR workflow: `CONTRIBUTING.md`
- [Agent Skills Spec](https://agentskills.io/specification)