CtrlK
BlogDocsLog inGet started
Tessl Logo

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)

80

1.33x
Quality

70%

Does it follow best practices?

Impact

100%

1.33x

Average score across 3 eval scenarios

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./.agents/skills/architecture/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Discovery

89%

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 well-structured skill description that clearly communicates both when to use it and what it covers. Its strongest aspects are the explicit 'Use when' clause with multiple concrete trigger scenarios and the project-specific terminology that makes it highly distinctive. The main weakness is that the 'what it does' portion leans more toward topics covered rather than concrete actions the skill enables.

DimensionReasoningScore

Specificity

The description names the domain (three-layer architecture, client pattern, container runtime, monorepo layout) and some actions (adding a new client method, adding a new container handler/service), but the actions are more about navigation and understanding than concrete operations. It's not vague, but it's not listing multiple specific concrete actions either.

2 / 3

Completeness

Explicitly answers both 'what' (covers three-layer architecture, client pattern, container runtime structure, monorepo layout) and 'when' (navigating codebase for first time, adding a new client method, adding a new container handler/service, understanding request flow). The 'Use when' clause is present and detailed.

3 / 3

Trigger Term Quality

Includes strong natural trigger terms that a developer would actually use: 'codebase', 'client method', 'container handler', 'service', 'Worker', 'Sandbox DO', 'container', 'monorepo layout', 'request flows', 'three-layer architecture'. These are terms a developer navigating this specific project would naturally mention.

3 / 3

Distinctiveness Conflict Risk

Highly specific to a particular project's architecture with distinct terms like 'Worker', 'Sandbox DO', 'three-layer architecture', and 'container runtime structure'. The '(project)' tag and specific architectural terminology make it very unlikely to conflict with other skills.

3 / 3

Total

11

/

12

Passed

Implementation

50%

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

This is a solid architectural overview skill that clearly maps the three-layer architecture, request flow paths, and monorepo structure with accurate file paths. Its main weaknesses are the lack of executable examples (no actual commands or code snippets to run), missing validation/verification steps in the workflow for adding new operations, and some unnecessary explanatory content that Claude would already understand. The content would benefit from concrete examples and explicit verification checkpoints.

Suggestions

Add executable examples for common tasks — e.g., a concrete code snippet showing how to add a new client method or service, with actual file content rather than just file paths to edit.

Add validation checkpoints to the 'When adding a new container control operation' workflow — e.g., 'Run `turbo test --filter=sandbox` to verify SDK-side changes before proceeding to step 3' and error recovery guidance.

Remove general knowledge content like explaining what npm workspaces are, what DI containers do, and generic Docker advice ('keep images lean, pin versions') — Claude already knows these concepts.

Consider splitting detailed sections (e.g., route-based client listing, container runtime internals) into separate reference files and linking to them from a leaner overview.

DimensionReasoningScore

Conciseness

The content is mostly efficient and well-structured, but includes some information Claude would already know (e.g., explaining what npm workspaces are, what DI containers do, what Ubuntu is). Some sections like 'Container Base Image' include general advice ('keep images lean') that is common knowledge. However, the architecture-specific details are genuinely useful and not padded excessively.

2 / 3

Actionability

The skill provides clear file paths and structural guidance (e.g., where to add new services, the 4-step process for adding container control operations), but lacks executable code examples, specific commands, or copy-paste ready snippets. The guidance is concrete in terms of architecture navigation but remains at the 'where to look' level rather than 'what to type'.

2 / 3

Workflow Clarity

The 'When adding a new container control operation' section provides a clear 4-step sequence, and the request flow diagrams are well-structured. However, there are no validation checkpoints or feedback loops — no mention of how to verify each step succeeded, no error recovery guidance, and no testing commands to run between steps.

2 / 3

Progressive Disclosure

The content is well-organized with clear headers and logical sections, but it's a monolithic document with no references to supporting files. Given the breadth of topics covered (architecture, request flow, container runtime, monorepo structure, base image), some content could be split into separate reference files. However, no bundle files exist, so this is evaluated in isolation — the organization within the single file is reasonable but could benefit from splitting.

2 / 3

Total

8

/

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.

Validation11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository
cloudflare/sandbox-sdk
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.