From 534fd45519023e1c72061a3baacea88347d54a55 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Mon, 19 Oct 2026 15:02:30 +0000 Subject: [PATCH 1/9] docs(agents): Add writing-sdk-specs skill Repo-local skill that points agents at the Writing SDK Specs page, has them check their own changes against it, and report pre-existing violations without fixing them. Listed in AGENTS.md and SKILL.md. --- .claude/skills/writing-sdk-specs/SKILL.md | 26 +++++++++++++++++++++++ AGENTS.md | 1 + SKILL.md | 1 + 3 files changed, 28 insertions(+) create mode 100644 .claude/skills/writing-sdk-specs/SKILL.md diff --git a/.claude/skills/writing-sdk-specs/SKILL.md b/.claude/skills/writing-sdk-specs/SKILL.md new file mode 100644 index 0000000000000..22100bbb30fa6 --- /dev/null +++ b/.claude/skills/writing-sdk-specs/SKILL.md @@ -0,0 +1,26 @@ +--- +name: writing-sdk-specs +description: Write, edit, or review SDK specs. Use when changing or reviewing any page under develop-docs/sdk/ that has spec_id frontmatter, or when creating a new SDK spec. +--- + +# Writing SDK Specs + +The rules live in [`develop-docs/sdk/getting-started/standards/writing-specs.mdx`](../../../develop-docs/sdk/getting-started/standards/writing-specs.mdx). That page is the source of truth. This skill only says when and how to apply it. + +## Steps + +1. **Read the guidelines.** Read `writing-specs.mdx` in full before changing a spec. Don't work from memory or from this file. +2. **Check whether the spec is legacy.** A spec is legacy if its frontmatter has no `spec_guidelines` field. +3. **Write to the guidelines.** + - **New spec:** follow the guidelines for the whole page and set `spec_guidelines: writing-specs@` to the current version of `writing-specs.mdx`. + - **Legacy spec:** make every requirement you add or change follow the guidelines. Leave the rest of the page as it is unless the user asks you to migrate it. Don't add `spec_guidelines` unless the whole page now conforms. +4. **Check your own work.** Re-read every requirement you added or changed against `writing-specs.mdx`, and fix any violations before you finish. +5. **Report existing violations.** List violations you noticed in content you didn't change, but don't fix them unless the user asks. Give the section and quote the text. + +## What to Report + +When you finish, briefly report: + +- Which guidelines version you followed. +- Whether the page is legacy or conforming, and whether you set `spec_guidelines`. +- Any pre-existing violations you found (or "none found"). diff --git a/AGENTS.md b/AGENTS.md index 0c692c1be4f92..e0f0c684b4c27 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -98,6 +98,7 @@ When writing requirements in `develop-docs/`: - **ALWAYS** run `/brand-guidelines` to audit any user-facing content before committing. See `.agents/skills/brand-guidelines/SKILL.md` - Use `docs-review` skill for Sentry style and voice review. See `.claude/skills/docs-review/SKILL.md` - Use `technical-docs` skill when writing or reviewing SDK documentation. See `.claude/skills/technical-docs/SKILL.md` +- Use `writing-sdk-specs` skill when writing, editing, or reviewing SDK specs (pages in `develop-docs/sdk/` with `spec_id` frontmatter). See `.claude/skills/writing-sdk-specs/SKILL.md` ## LLM-Friendly MD Exports diff --git a/SKILL.md b/SKILL.md index d7e9cc3b51cf3..bea3a8643043b 100644 --- a/SKILL.md +++ b/SKILL.md @@ -32,5 +32,6 @@ Source repo: https://github.com/getsentry/sentry-for-ai | Brand Guidelines | `.agents/skills/brand-guidelines/` | Audit content against Sentry brand voice | | Docs Review | `.claude/skills/docs-review/SKILL.md` | Sentry documentation style guide | | Technical Docs | `.claude/skills/technical-docs/SKILL.md` | Writing SDK and technical documentation | +| Writing SDK Specs | `.claude/skills/writing-sdk-specs/SKILL.md` | Writing and reviewing SDK specs in `develop-docs/sdk/` | | Commit | `.agents/skills/commit/SKILL.md` | Sentry conventional commit format | | Create Branch | `.agents/skills/create-branch/SKILL.md` | Branch naming conventions | From 07c18efa09bc538134f09dae43f946f25b172e43 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Mon, 19 Oct 2026 15:06:50 +0000 Subject: [PATCH 2/9] ref(agents): Manage writing-sdk-specs skill with dotagents Move the skill from .claude/skills/ to .agents/skills/ and declare it in agents.toml with a path: source, matching the dotagents convention for repo-local skills. Keep a .claude/skills symlink like the existing ones. --- {.claude => .agents}/skills/writing-sdk-specs/SKILL.md | 0 .claude/skills/writing-sdk-specs | 1 + AGENTS.md | 4 +++- SKILL.md | 2 +- agents.toml | 4 ++++ 5 files changed, 9 insertions(+), 2 deletions(-) rename {.claude => .agents}/skills/writing-sdk-specs/SKILL.md (100%) create mode 120000 .claude/skills/writing-sdk-specs diff --git a/.claude/skills/writing-sdk-specs/SKILL.md b/.agents/skills/writing-sdk-specs/SKILL.md similarity index 100% rename from .claude/skills/writing-sdk-specs/SKILL.md rename to .agents/skills/writing-sdk-specs/SKILL.md diff --git a/.claude/skills/writing-sdk-specs b/.claude/skills/writing-sdk-specs new file mode 120000 index 0000000000000..c69df90dee5c2 --- /dev/null +++ b/.claude/skills/writing-sdk-specs @@ -0,0 +1 @@ +../../.agents/skills/writing-sdk-specs \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index e0f0c684b4c27..40143c0306709 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -78,6 +78,8 @@ To bypass the hook once without marking the file, use `SKIP=trailing-slashes git Managed skills in `.agents/skills/` are not checked in. Run `make develop` (or `npx -y @sentry/dotagents install`) to install them before relying on skills like `/brand-guidelines` or `/commit`. +Repo-specific skills live in `.agents/skills//`, are checked in, and are declared in `agents.toml` with a `path:` source (for example `writing-sdk-specs`). + ## Developer Documentation (develop-docs/) When writing requirements in `develop-docs/`: @@ -98,7 +100,7 @@ When writing requirements in `develop-docs/`: - **ALWAYS** run `/brand-guidelines` to audit any user-facing content before committing. See `.agents/skills/brand-guidelines/SKILL.md` - Use `docs-review` skill for Sentry style and voice review. See `.claude/skills/docs-review/SKILL.md` - Use `technical-docs` skill when writing or reviewing SDK documentation. See `.claude/skills/technical-docs/SKILL.md` -- Use `writing-sdk-specs` skill when writing, editing, or reviewing SDK specs (pages in `develop-docs/sdk/` with `spec_id` frontmatter). See `.claude/skills/writing-sdk-specs/SKILL.md` +- Use `writing-sdk-specs` skill when writing, editing, or reviewing SDK specs (pages in `develop-docs/sdk/` with `spec_id` frontmatter). See `.agents/skills/writing-sdk-specs/SKILL.md` ## LLM-Friendly MD Exports diff --git a/SKILL.md b/SKILL.md index bea3a8643043b..4267364ca6c35 100644 --- a/SKILL.md +++ b/SKILL.md @@ -32,6 +32,6 @@ Source repo: https://github.com/getsentry/sentry-for-ai | Brand Guidelines | `.agents/skills/brand-guidelines/` | Audit content against Sentry brand voice | | Docs Review | `.claude/skills/docs-review/SKILL.md` | Sentry documentation style guide | | Technical Docs | `.claude/skills/technical-docs/SKILL.md` | Writing SDK and technical documentation | -| Writing SDK Specs | `.claude/skills/writing-sdk-specs/SKILL.md` | Writing and reviewing SDK specs in `develop-docs/sdk/` | +| Writing SDK Specs | `.agents/skills/writing-sdk-specs/SKILL.md` | Writing and reviewing SDK specs in `develop-docs/sdk/` | | Commit | `.agents/skills/commit/SKILL.md` | Sentry conventional commit format | | Create Branch | `.agents/skills/create-branch/SKILL.md` | Branch naming conventions | diff --git a/agents.toml b/agents.toml index 1ae8bf208e65a..f3b08c363cb90 100644 --- a/agents.toml +++ b/agents.toml @@ -27,3 +27,7 @@ source = "getsentry/skills" [[skills]] name = "create-branch" source = "getsentry/skills" + +[[skills]] +name = "writing-sdk-specs" +source = "path:.agents/skills/writing-sdk-specs" From 127d8d0ba7855ea927ed7638b87b8840ac6d7d6b Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Mon, 19 Oct 2026 15:21:27 +0000 Subject: [PATCH 3/9] docs(agents): Drop writing-sdk-specs row from SKILL.md The root SKILL.md is a routing guide, not how skills are discovered. AGENTS.md already lists the skill. --- SKILL.md | 1 - 1 file changed, 1 deletion(-) diff --git a/SKILL.md b/SKILL.md index 4267364ca6c35..d7e9cc3b51cf3 100644 --- a/SKILL.md +++ b/SKILL.md @@ -32,6 +32,5 @@ Source repo: https://github.com/getsentry/sentry-for-ai | Brand Guidelines | `.agents/skills/brand-guidelines/` | Audit content against Sentry brand voice | | Docs Review | `.claude/skills/docs-review/SKILL.md` | Sentry documentation style guide | | Technical Docs | `.claude/skills/technical-docs/SKILL.md` | Writing SDK and technical documentation | -| Writing SDK Specs | `.agents/skills/writing-sdk-specs/SKILL.md` | Writing and reviewing SDK specs in `develop-docs/sdk/` | | Commit | `.agents/skills/commit/SKILL.md` | Sentry conventional commit format | | Create Branch | `.agents/skills/create-branch/SKILL.md` | Branch naming conventions | From ec7c08381d2e1a9b36064243e85e9a22e86be95f Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Mon, 19 Oct 2026 15:56:46 +0000 Subject: [PATCH 4/9] docs(agents): Skip process specs in writing-sdk-specs skill --- .agents/skills/writing-sdk-specs/SKILL.md | 4 ++-- AGENTS.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.agents/skills/writing-sdk-specs/SKILL.md b/.agents/skills/writing-sdk-specs/SKILL.md index 22100bbb30fa6..0e95c5ab3e51e 100644 --- a/.agents/skills/writing-sdk-specs/SKILL.md +++ b/.agents/skills/writing-sdk-specs/SKILL.md @@ -1,6 +1,6 @@ --- name: writing-sdk-specs -description: Write, edit, or review SDK specs. Use when changing or reviewing any page under develop-docs/sdk/ that has spec_id frontmatter, or when creating a new SDK spec. +description: Write, edit, or review SDK specs. Use when changing or reviewing any page under develop-docs/sdk/ that has spec_id frontmatter (except process specs with spec_kind: process), or when creating a new SDK spec. --- # Writing SDK Specs @@ -10,7 +10,7 @@ The rules live in [`develop-docs/sdk/getting-started/standards/writing-specs.mdx ## Steps 1. **Read the guidelines.** Read `writing-specs.mdx` in full before changing a spec. Don't work from memory or from this file. -2. **Check whether the spec is legacy.** A spec is legacy if its frontmatter has no `spec_guidelines` field. +2. **Check what kind of spec it is.** If its frontmatter has `spec_kind: process` (playbooks and engineering standards), the guidelines don't apply: skip the remaining steps. Otherwise, the spec is legacy if its frontmatter has no `spec_guidelines` field. 3. **Write to the guidelines.** - **New spec:** follow the guidelines for the whole page and set `spec_guidelines: writing-specs@` to the current version of `writing-specs.mdx`. - **Legacy spec:** make every requirement you add or change follow the guidelines. Leave the rest of the page as it is unless the user asks you to migrate it. Don't add `spec_guidelines` unless the whole page now conforms. diff --git a/AGENTS.md b/AGENTS.md index 40143c0306709..dd1ef1ab2fe9e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -100,7 +100,7 @@ When writing requirements in `develop-docs/`: - **ALWAYS** run `/brand-guidelines` to audit any user-facing content before committing. See `.agents/skills/brand-guidelines/SKILL.md` - Use `docs-review` skill for Sentry style and voice review. See `.claude/skills/docs-review/SKILL.md` - Use `technical-docs` skill when writing or reviewing SDK documentation. See `.claude/skills/technical-docs/SKILL.md` -- Use `writing-sdk-specs` skill when writing, editing, or reviewing SDK specs (pages in `develop-docs/sdk/` with `spec_id` frontmatter). See `.agents/skills/writing-sdk-specs/SKILL.md` +- Use `writing-sdk-specs` skill when writing, editing, or reviewing SDK specs (pages in `develop-docs/sdk/` with `spec_id` frontmatter, except those with `spec_kind: process`). See `.agents/skills/writing-sdk-specs/SKILL.md` ## LLM-Friendly MD Exports From 0a430238fcb0557ff616c95973c11b8dfeed8517 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:33:18 +0000 Subject: [PATCH 5/9] docs(agents): Report requirement changes in migrations --- .agents/skills/writing-sdk-specs/SKILL.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.agents/skills/writing-sdk-specs/SKILL.md b/.agents/skills/writing-sdk-specs/SKILL.md index 0e95c5ab3e51e..a0cf71deea234 100644 --- a/.agents/skills/writing-sdk-specs/SKILL.md +++ b/.agents/skills/writing-sdk-specs/SKILL.md @@ -24,3 +24,4 @@ When you finish, briefly report: - Which guidelines version you followed. - Whether the page is legacy or conforming, and whether you set `spec_guidelines`. - Any pre-existing violations you found (or "none found"). +- For a migration: every requirement you added, removed, or whose level or meaning changed, so a reviewer can check each one. From de1e631f6b8d74e2dc5a5e849353ab19e4dc923f Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Mon, 19 Oct 2026 17:20:51 +0000 Subject: [PATCH 6/9] docs(agents): Scope technical-docs skill to user-facing docs, not specs --- .claude/skills/technical-docs/SKILL.md | 2 +- AGENTS.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.claude/skills/technical-docs/SKILL.md b/.claude/skills/technical-docs/SKILL.md index 4b75b004556fb..2fe024a41e2d7 100644 --- a/.claude/skills/technical-docs/SKILL.md +++ b/.claude/skills/technical-docs/SKILL.md @@ -1,6 +1,6 @@ --- name: technical-docs -description: Write and review technical documentation for Sentry SDK docs. Use when creating, editing, or reviewing documentation pages, especially MDX files in docs/platforms/. +description: Write and review user-facing technical documentation for Sentry SDK docs. Use when creating, editing, or reviewing pages in docs/, platform-includes/, or includes/, especially MDX files in docs/platforms/. Does not apply to SDK specs in develop-docs/sdk/; use writing-sdk-specs for those. --- # Technical Documentation Writing diff --git a/AGENTS.md b/AGENTS.md index dd1ef1ab2fe9e..6bbe75ce6af95 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -99,7 +99,7 @@ When writing requirements in `develop-docs/`: - **ALWAYS** run `/brand-guidelines` to audit any user-facing content before committing. See `.agents/skills/brand-guidelines/SKILL.md` - Use `docs-review` skill for Sentry style and voice review. See `.claude/skills/docs-review/SKILL.md` -- Use `technical-docs` skill when writing or reviewing SDK documentation. See `.claude/skills/technical-docs/SKILL.md` +- Use `technical-docs` skill when writing or reviewing user-facing SDK docs (`docs/platforms/`). See `.claude/skills/technical-docs/SKILL.md` - Use `writing-sdk-specs` skill when writing, editing, or reviewing SDK specs (pages in `develop-docs/sdk/` with `spec_id` frontmatter, except those with `spec_kind: process`). See `.agents/skills/writing-sdk-specs/SKILL.md` ## LLM-Friendly MD Exports From 7d3591a2e4e3e1616e7cfc0e61a68c4ff178f34f Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Mon, 19 Oct 2026 17:32:26 +0000 Subject: [PATCH 7/9] docs(agents): Push back on requests that break the spec guidelines --- .agents/skills/writing-sdk-specs/SKILL.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.agents/skills/writing-sdk-specs/SKILL.md b/.agents/skills/writing-sdk-specs/SKILL.md index a0cf71deea234..180930b1181ce 100644 --- a/.agents/skills/writing-sdk-specs/SKILL.md +++ b/.agents/skills/writing-sdk-specs/SKILL.md @@ -7,6 +7,10 @@ description: Write, edit, or review SDK specs. Use when changing or reviewing an The rules live in [`develop-docs/sdk/getting-started/standards/writing-specs.mdx`](../../../develop-docs/sdk/getting-started/standards/writing-specs.mdx). That page is the source of truth. This skill only says when and how to apply it. +## Requests That Conflict With the Guidelines + +The guidelines take priority over requests that would break them, because the person asking may not know them. Don't make the change. Explain which rule it breaks, link the relevant section of `writing-specs.mdx`, and suggest a change that conforms. If the user still wants it after that, make the change and list it in your report as a violation. + ## Steps 1. **Read the guidelines.** Read `writing-specs.mdx` in full before changing a spec. Don't work from memory or from this file. @@ -24,4 +28,5 @@ When you finish, briefly report: - Which guidelines version you followed. - Whether the page is legacy or conforming, and whether you set `spec_guidelines`. - Any pre-existing violations you found (or "none found"). +- Any requested changes you pushed back on, and any violations you made because the user insisted. - For a migration: every requirement you added, removed, or whose level or meaning changed, so a reviewer can check each one. From 643c67d0bfeae912a9645ae2667a15e2dd676a9a Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Tue, 20 Oct 2026 08:45:45 +0000 Subject: [PATCH 8/9] docs(agents): Link rendered Writing SDK Specs page when pushing back --- .agents/skills/writing-sdk-specs/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/writing-sdk-specs/SKILL.md b/.agents/skills/writing-sdk-specs/SKILL.md index 180930b1181ce..71e23167bd028 100644 --- a/.agents/skills/writing-sdk-specs/SKILL.md +++ b/.agents/skills/writing-sdk-specs/SKILL.md @@ -9,7 +9,7 @@ The rules live in [`develop-docs/sdk/getting-started/standards/writing-specs.mdx ## Requests That Conflict With the Guidelines -The guidelines take priority over requests that would break them, because the person asking may not know them. Don't make the change. Explain which rule it breaks, link the relevant section of `writing-specs.mdx`, and suggest a change that conforms. If the user still wants it after that, make the change and list it in your report as a violation. +The guidelines take priority over requests that would break them, because the person asking may not know them. Don't make the change. Explain which rule it breaks, link the relevant section of the rendered page (`https://develop.sentry.dev/sdk/getting-started/standards/writing-specs/#`, e.g. `#legacy-specs`), and suggest a change that conforms. If the user still wants it after that, make the change and list it in your report as a violation. ## Steps From ea4dec5aafc1c0d4266839ac5626688742210555 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Tue, 20 Oct 2026 08:55:24 +0000 Subject: [PATCH 9/9] docs(agents): Add whole-spec migration steps with brief investigation and batched questions --- .agents/skills/writing-sdk-specs/SKILL.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/.agents/skills/writing-sdk-specs/SKILL.md b/.agents/skills/writing-sdk-specs/SKILL.md index 71e23167bd028..1439948079f48 100644 --- a/.agents/skills/writing-sdk-specs/SKILL.md +++ b/.agents/skills/writing-sdk-specs/SKILL.md @@ -17,10 +17,23 @@ The guidelines take priority over requests that would break them, because the pe 2. **Check what kind of spec it is.** If its frontmatter has `spec_kind: process` (playbooks and engineering standards), the guidelines don't apply: skip the remaining steps. Otherwise, the spec is legacy if its frontmatter has no `spec_guidelines` field. 3. **Write to the guidelines.** - **New spec:** follow the guidelines for the whole page and set `spec_guidelines: writing-specs@` to the current version of `writing-specs.mdx`. - - **Legacy spec:** make every requirement you add or change follow the guidelines. Leave the rest of the page as it is unless the user asks you to migrate it. Don't add `spec_guidelines` unless the whole page now conforms. + - **Legacy spec:** make every requirement you add or change follow the guidelines. Leave the rest of the page as it is unless the user asks you to migrate it (see [Migrating a Whole Spec](#migrating-a-whole-spec)). Don't add `spec_guidelines` unless the whole page now conforms. 4. **Check your own work.** Re-read every requirement you added or changed against `writing-specs.mdx`, and fix any violations before you finish. 5. **Report existing violations.** List violations you noticed in content you didn't change, but don't fix them unless the user asks. Give the section and quote the text. +## Migrating a Whole Spec + +Follow "Migrating a legacy spec" in the guidelines. Before editing, list the open questions: ones whose 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. For example, whether a MUST passes the Section 6 test, or what observable intent a non-observable requirement serves. + +Investigate each open question briefly, with a few targeted searches rather than a full audit: + +- **Relay** (`getsentry/relay`): does it reject, drop, or reinterpret data that violates the requirement? +- **A few SDKs** (for example `sentry-python`, `sentry-javascript`, and one mobile SDK): do they implement it, and does any have a reason to deviate? + +If the code settles a question, apply the answer and cite the evidence (file paths or links) in your report. Relay not checking something doesn't prove it's safe, since other parts of Sentry may still depend on it. SDKs agreeing is not a reason for a MUST. If you can't access the code, say so and treat the question as open. + +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 your report. + ## What to Report When you finish, briefly report: