cell-architecture
Reference and active migration guide for Sentry's cell architecture. Explains what cells and localities are and why they're different, how requests reach cells via Synapse API routing, ingestion routing, and the control silo gateway, and how to safely query cross-cell data without silently missing results. The migration section covers how to do migration work: draining the URL_NAME_TO_ACTION registry in test_urls.py to zero (with a recipe for each action type), rolling deploy safety and the two-phase pattern required by independent sentry/getsentry deploys, and the region -> cell rename including what not to rename (DB columns, AWS refs, uptime regions, billing address). Also documents known issues with proposed fixes: org listing and creation without a slug, integration TeamLinkageView routing, Jira cross-cell fan-out, and relocation endpoint routing.
67
80%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.agents/skills/cell-architecture/SKILL.mdQuality
Discovery
82%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a highly detailed and specific skill description that excels at explaining what the skill covers, with rich domain-specific terminology that would serve well as trigger terms. Its main weakness is the absence of an explicit 'Use when...' clause, which means Claude must infer when to select this skill rather than being explicitly guided. The description is also quite long, though the verbosity is justified by the complexity of the domain.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when working on Sentry cell architecture migration, asking about cross-cell data queries, Synapse routing, deploy safety patterns, or the region-to-cell rename.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description lists numerous specific concrete actions and concepts: draining URL_NAME_TO_ACTION registry, two-phase deploy pattern, Synapse API routing, ingestion routing, control silo gateway, cross-cell data querying, region->cell rename with explicit exclusions (DB columns, AWS refs, uptime regions, billing address), and specific known issues (TeamLinkageView routing, Jira cross-cell fan-out, relocation endpoint routing). | 3 / 3 |
Completeness | The description thoroughly answers 'what does this do' with extensive detail about capabilities and content, but lacks an explicit 'Use when...' clause or equivalent trigger guidance. The when is only implied by the nature of the content described. | 2 / 3 |
Trigger Term Quality | Contains strong natural keywords a developer would use: 'cell architecture', 'cells', 'localities', 'Synapse', 'control silo', 'cross-cell', 'rolling deploy', 'region', 'migration', 'test_urls.py', 'URL_NAME_TO_ACTION', 'Jira', 'integration', 'relocation endpoint'. These are terms Sentry developers would naturally use when asking about cell architecture migration. | 3 / 3 |
Distinctiveness Conflict Risk | Extremely specific to Sentry's cell architecture migration with highly distinctive terms like 'Synapse API routing', 'control silo gateway', 'URL_NAME_TO_ACTION registry', and specific Sentry integration names. This is unlikely to conflict with any other skill. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, highly actionable skill that serves as both an architecture reference and a migration guide for Sentry's cell architecture. Its greatest strengths are the concrete, executable guidance (specific file paths, code patterns, action-type recipes) and clear workflow sequencing (two-phase deploys, rename guardrails). The main weakness is its length — combining stable architecture reference with temporary migration content in a single file without bundle support makes it heavier than ideal, and some sections could be tightened.
Suggestions
Consider splitting the 'Active Migration' section (including Known Issues) into a separate MIGRATION.md file referenced from the main skill, since it's explicitly temporary and serves a different purpose than the architecture reference.
Tighten the 'Paths Into a Cell' section — the DSN host/error embed widget paragraph under Ingestion could be condensed to 2-3 sentences without losing actionable information.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is generally well-written and avoids explaining basic concepts Claude already knows, but it's quite long (~300+ lines) with some sections that could be tightened. The Known Issues section is detailed and useful but verbose in places. The architecture explanation is necessary context but some paragraphs (e.g., the DSN host explanation, the error embed widget detail) could be more concise. | 2 / 3 |
Actionability | Highly actionable throughout: concrete code examples (e.g., `org.locality.to_url()`), specific file paths (`getsentry/tests/getsentry/test_urls.py`), exact action labels with clear definitions for each (`TO_BE_REPLACED_WITH_ORG_SCOPED_VARIANT`, etc.), specific URL patterns (`^api/0/_admin/cells/(?P<cell_id>[^/]+)/`), bash commands for local dev, and precise two-phase deploy recipes with DB column rename patterns (`db_column="old_name"`). | 3 / 3 |
Workflow Clarity | Multi-step processes are clearly sequenced with explicit validation: the two-phase deploy pattern is well-defined with Phase 1/Phase 2, the URL_NAME_TO_ACTION drain process has clear per-action-type recipes, the region->cell rename has explicit 'do NOT rename' guardrails and caution areas. The rolling deploy section explicitly addresses error recovery (keeping old names as aliases, dual-emission of metrics). Known issues each have a problem statement and proposed fix. | 3 / 3 |
Progressive Disclosure | The document is well-structured with clear headers and internal anchor links, and references other skills (hybrid-cloud-rpc, hybrid-cloud-outboxes) appropriately. However, with no bundle files, this is a monolithic ~300-line document that could benefit from splitting the Known Issues and Migration Guide into separate referenced files. The architecture reference and active migration guide serve different audiences and lifespans. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- getsentry/sentry
- Commit
552fb5c
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.