docs(agents): Add writing-sdk-specs skill

[sentry-junior]

Stacked on #20081, which adds the Writing SDK Specs page this skill points to.

Adds a repo-local agent skill at .agents/skills/writing-sdk-specs/SKILL.md, managed with dotagents. It's declared in agents.toml with source = "path:.agents/skills/writing-sdk-specs", the same pattern getsentry/sentry-javascript uses for its repo-local skills. Because the skill isn't a managed install, dotagents leaves it out of .agents/.gitignore, so it's checked in. .claude/skills/writing-sdk-specs is a symlink to it, like the existing commit and create-branch links. The skill holds no rules of its own. develop-docs/sdk/getting-started/standards/writing-specs.mdx stays the only source of truth, and the skill tells agents to:

1. Read writing-specs.mdx in full before changing a spec.
2. Skip process specs (spec_kind: process, i.e. playbooks and engineering standards), which the guidelines don't cover. Otherwise check whether the spec is legacy, meaning it has no spec_guidelines field.
3. Apply the guidelines:
   • New specs: follow them for the whole page and set spec_guidelines.
   • Legacy specs: only requirements they add or change have to follow them. They don't migrate the rest of the page unless asked, and they don't set spec_guidelines unless the whole page conforms.
4. Check every requirement they added or changed against the guidelines.
5. Report violations they find in content they didn't touch, without fixing them unless asked. For migrations, also report every requirement they added, removed, or whose level or meaning changed, so a reviewer can check each one.

So agents find the skill without anyone pointing them to it, it's also listed in AGENTS.md (Content Authoring). AGENTS.md also gets one sentence saying repo-specific skills live in .agents/skills/ and are declared with path: sources.

Verified: npx @sentry/dotagents --project install installs the skill, and --project doctor passes all checks.

Note: the existing "Developer Documentation" section in AGENTS.md (RFC 2119 keywords in bold, plus the RFC alert) is unchanged. It still applies to all of develop-docs/, and it doesn't conflict with the new page.

via @szokeasaurusrex.

--

View Junior Session [Sentry]

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
develop-docs	Ready	Preview	Oct 20, 2026 9:01am UTC
sentry-docs	Ready	Preview	Oct 20, 2026 9:01am UTC

[szokeasaurusrex]

We may want to add a section for migrating docs which invites the agent to ask questions:

## Migrating a Whole Spec
Follow "Migrating a legacy spec" in the guidelines. Before editing,
identify open questions: ones where the answer would change a
requirement's level or meaning AND depends on facts about Sentry or
SDKs that the guidelines and the spec don't settle (e.g. whether a
MUST passes the Section 6 test, or what observable intent a
non-observable requirement serves).
For each open question, first do a brief investigation of the relevant
code:
- Relay (getsentry/relay): does it reject, drop, or reinterpret data
  that violates the requirement?
- A few SDKs (e.g. sentry-python, sentry-javascript, and one mobile
  SDK): do they implement it, and does any have a reason to deviate?
Keep it brief: a few targeted searches per question, not a full audit.
If the code settles the question, apply the answer and cite the
evidence (file paths or links) in your report. Relay not checking
something is not proof that it's safe, and SDKs agreeing is not a
reason for a MUST.
Then ask the remaining questions in one batch, with what you found for
each. Don't ask about anything the guidelines decide or give a default
for; apply the default and flag it in the report instead.

That might be a bit too verbose, but given this is for agent consumption that could be OK. But make sure it makes sense before adding