architecture

Use when navigating the codebase for the first time, adding a new client method, adding a new container handler/service, or understanding how a request flows from Worker through the Sandbox DO into the container. Covers the three-layer architecture, client pattern, container runtime structure, and monorepo layout. (project)

1.97x

Quality

85%

Does it follow best practices?

Impact

95%

1.97x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Quality

Content

75%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-organized architecture reference that provides genuinely non-obvious, project-specific guidance with concrete paths and a clear change-recipe. Its main weaknesses are moderate internal redundancy (the control path and placement rules are each explained twice) and content that is beginning to outgrow a single SKILL.md.

Suggestions

Collapse the duplication between 'Request Flow' and 'Primary Control Path' into one section, and state the container-control placement rule once instead of at both the top and bottom of the clients section.

Move the full specialized-client roster and the container base-image inventory into references/ files (e.g., CLIENTS.md, BASE_IMAGE.md) to keep SKILL.md a lean overview.

Add one short example of a control-plane method and its mirrored SDK-side call so the 'mirror the call' step in the workflow is concretely executable.

Dimension	Reasoning	Score
Conciseness	The body is dense with project-specific facts Claude cannot infer (paths, wire protocol, port constraints), but the 'Primary Control Path' section re-explains the path already diagrammed in 'Request Flow', and the rule about where control capabilities belong is stated twice (at the top of the clients section and again after the client list).	4 / 5
Actionability	Guidance is concrete and executable: exact package paths, a numbered recipe for adding a control operation, and per-domain client responsibilities. It falls short of a 5 only because there are no example code or command snippets for the common cases (e.g., what a control-plane method signature looks like).	4 / 5
Workflow Clarity	The 'When adding a new container control operation' sequence is clearly ordered (service → control-plane method → SDK mirror → tests on both sides) with an explicit verification checkpoint ('Add unit tests on both sides; add an E2E test if it touches real shell/filesystem behavior'). No error-recovery loop or symmetry check on the mirror step keeps it at 4.	4 / 5
Progressive Disclosure	No bundle files exist, so this is scored on the single-file structure: clear section headers, each topic self-contained, no nested or buried references. At ~135 lines, some content (the full specialized-client roster, the base-image inventory) could live in a reference file, which is the minor gap.	4 / 5
	Total	16 / 20 Passed

Description

95%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description: it pairs an explicit, multi-trigger 'Use when' clause with a concrete enumeration of what the skill covers, all in the correct third-person voice. The only weakness is that the capability side leans on the generic verb 'Covers' rather than naming more distinct actions.

Dimension	Reasoning	Score
Specificity	Enumerates several concrete coverage areas ('three-layer architecture, client pattern, container runtime structure, and monorepo layout') and concrete tasks ('adding a new client method', 'adding a new container handler/service'), but the 'what' verb is a generic 'Covers', leaving minor gaps versus fully comprehensive.	4 / 5
Completeness	Explicitly answers both questions: a clear 'what' ('Covers the three-layer architecture, client pattern, container runtime structure, and monorepo layout') and a fully explicit 'Use when...' clause with four concrete trigger phrases.	5 / 5
Trigger Term Quality	Triggers are natural phrases users would actually say in this repo ('navigating the codebase for the first time', 'adding a new client method', 'understanding how a request flows from Worker through the Sandbox DO into the container'), with comprehensive coverage including synonyms and concrete scenarios.	5 / 5
Distinctiveness Conflict Risk	Scoped tightly to this project's architecture (Sandbox DO, container runtime, monorepo layout) with distinct triggers like 'adding a new container handler/service'; essentially no risk of triggering for the wrong skill.	5 / 5
	Total	19 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: cloudflare/sandbox-sdk
Path: .agents/skills/architecture/SKILL.md
Commit: 831b8c5

Reviewed: 7 days ago

Table of Contents

Discovery Implementation Validation

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.