CtrlK
BlogDocsLog inGet started
Tessl Logo

sdk-seam

Discipline for the seam between two SDKs (or two sides of one contract) that the same hand writes. The failure mode: "we own both sides" produces dirty contracts no foreign reviewer would accept. The exercise: pretend the other side is FFI, IPC, or a network protocol you cannot rewrite. Spawn an adversarial subagent profiled as the producer's maintainer; negotiate the change as a feature request, not a PR. Companion to $sdk-design. Language-agnostic — applies to a TS package + its consumer, a Rust crate + its WASM binding, two services sharing a wire format, or any other boundary the same author writes both ends of.

53

Quality

60%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/sdk-seam/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

67%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.

The body is a well-structured, genuinely actionable doctrine skill: concrete artifact requirements, a copy-paste subagent brief, explicit branch handling with error recovery, and a smells checklist. Its weaknesses are repetition of the same few rules across sections and total inlining of ~334 lines where a filled-in FEEDBACKS.md example and the subagent brief template would fit naturally in reference files.

Suggestions

Consolidate the repeated statements of 'contract first / no edit-in-tandem / never name the consumer' into their canonical sections (the Stage patterns) and let 'The short version' be the only recap.

Move the subagent brief (Step 2) into a template file under references/ and show a filled-in example FEEDBACKS.md so both are copy-paste ready and the body shrinks toward an overview.

Add an explicit pre-spawn checkpoint — a short list of criteria the FEEDBACKS.md must satisfy before spawning — to close the workflow's only validation gap.

DimensionReasoningScore

Conciseness

The ~334-line body is mostly original doctrine (not concepts Claude already knows), so much of it earns its tokens, but the core rules are restated repeatedly — 'contract first', 'no edit-in-tandem', and 'just add the field' recur across 'The failure mode', the Stage sections, 'Why this is more than ceremony', and 'The short version' — and passages like 'This is the mechanism that keeps the contract unopinionated...' re-explain points already made. This is 'mostly efficient but includes some unnecessary explanation or could be tightened' rather than the padded verbosity of a 2.

3 / 5

Actionability

For an instruction-only skill the guidance is concrete and near copy-paste ready: the five numbered MUST-contents and three MUST-NOTs for the FEEDBACKS.md artifact, the full verbatim subagent brief (accept/counter-propose/refuse with shipping instructions), the three-outcome verdict handling, and the four procedural patterns each with a named anti-pattern. Minor gaps keep it at 4: the FEEDBACKS.md is specified by requirements rather than shown as a filled-in example, and the worked example's contract fragments are illustrative rather than complete.

4 / 5

Workflow Clarity

The multi-step process is clearly sequenced (write FEEDBACKS.md → spawn the profiled subagent → read the verdict and branch on accept/counter/refuse), with an explicit error-recovery path (refusal is absorbed or escalated, never overridden; don't re-spawn to get a different answer), test checkpoints ('Producer tests run; consumer tests run'), a smells checklist as a stop-and-reset signal, and a 'When NOT to use' gate. Not 5 because validation of the FEEDBACKS.md artifact itself before spawning is not checkpointed, and some steps (tool scoping, escalation rewrite) are described rather than sequenced.

4 / 5

Progressive Disclosure

No bundle files exist (no references/, scripts/, or assets/), so structure rests on the body itself: well-ordered sections, a flow diagram, and one clearly signaled one-level cross-skill reference ('Companion to sdk-design'). The 50-line simple-skill exemption doesn't apply, and the ~334-line body inlines content that could arguably be split (the subagent brief template, the worked example), which keeps it at 4 ('most content appropriately placed; references mostly clear; minor organization gaps') rather than 5.

4 / 5

Total

15

/

20

Passed

Description

53%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.

The description communicates a distinctive and genuinely specific concept, but its philosophical framing consumes space that should go to enumerated capabilities and explicit trigger guidance. There is no 'Use when...' clause, so the 'when' is only weakly implied by the applicability list, and the trigger vocabulary is more author-jargon ('seam', 'dirty contracts') than the words a user would naturally say.

Suggestions

Add an explicit trigger clause, e.g. 'Use when you find yourself editing both sides of a package boundary, API contract, crate+binding, or shared wire format in the same change.'

Lead with concrete actions instead of abstract framing — enumerate what the skill actually has the agent do (restate the change as a feature request, spawn a producer-maintainer subagent, ship contract-first with producer-side tests).

Include natural user phrasings as trigger terms ("I control both sides", "API boundary", "contract change", "breaking change") alongside the technical ones (FFI, IPC, wire format).

DimensionReasoningScore

Specificity

The description names the domain ("the seam between two SDKs (or two sides of one contract) that the same hand writes") and 1-2 concrete actions ("Spawn an adversarial subagent profiled as the producer's maintainer; negotiate the change as a feature request"), but much of its budget goes to abstract framing ("Discipline for the seam", "The failure mode", "The exercise") rather than an enumeration of capabilities. It matches the anchor 'names domain and 1-2 concrete actions, but not comprehensive' — not 4, which requires a list of several specific actions with only minor gaps.

3 / 5

Completeness

The 'what' is clear (keep the joint between two same-author SDKs clean; spawn a producer-maintainer subagent and negotiate as a feature request), but the 'when' is only implied via the applicability list ("applies to a TS package + its consumer, a Rust crate + its WASM binding...") rather than an explicit 'Use when...' trigger clause, which caps completeness at 3 per the judging guidelines. It is above score 2 because the 'what' is concrete, and not 4 because the trigger guidance is implicit rather than explicit.

3 / 5

Trigger Term Quality

Relevant keywords exist ("SDK", "FFI", "IPC", "network protocol", "Rust crate + its WASM binding", "two services sharing a wire format") but they lean technical; the natural phrases a user would say ("I control both sides of this API", "API contract", "package boundary", "breaking change") are largely absent. This is 'some relevant keywords but missing common variations or synonyms' — below 4's 'good keyword coverage', above 2's generic-only.

3 / 5

Distinctiveness Conflict Risk

The niche is clear and specific (seam discipline, producer-maintainer subagent, contract-first sequencing) and mostly distinct, with only minor overlap risk against its own companion ('$sdk-design', 'Companion to $sdk-design' — a closely related skill a user could confuse it with). Not 5 because the companion-skill adjacency is a real, if minor, conflict surface.

4 / 5

Total

13

/

20

Passed

Validation

93%

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

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

relative_links

Relative link issues: 1 suspicious

Warning

Total

15

/

16

Passed

Repository
gridaco/grida
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.