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.

Quality

55%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

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

Quality

Content

55%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 highly actionable and clearly sequenced with concrete templates, an explicit subagent brief, and decision branches, but it is a verbose monolith that restates its thesis repeatedly and does not split any detail into referenced files, capping progressive disclosure and conciseness.

Suggestions

Trim the overlapping rationale sections ('Why this is more than ceremony', 'Smells', 'When the discipline gets relaxed') that restate 'don't edit both sides at once'; fold the essential bits into the short version.

Extract the full worked-example table and/or the subagent brief into a referenced file (e.g. references/EXAMPLE.md) to reduce the body and enable one-level-deep progressive disclosure.

Make the validation checkpoints explicit pass/fail gates ('Only when producer tests pass: update the consumer') rather than the softer 'Producer tests run; consumer tests run.'

Dimension	Reasoning	Score
Conciseness	The body is noticeably verbose for a procedural discipline — the failure-mode rationale, 'Why this is more than ceremony', 'When NOT to use', and 'Smells' sections restate the same core idea (don't edit both sides at once) several times with overlapping prose; padding could be trimmed without losing clarity.	2 / 5
Actionability	Provides concrete, executable guidance: an explicit subagent brief to paste, a 4-part feature-request template (MUST/MUST NOT lists), an ASCII flow diagram, and a worked example table — minor gaps only (no literal copy-paste subagent invocation command).	4 / 5
Workflow Clarity	Clear sequenced flow (write FEEDBACKS.md → profile subagent → read verdict → update consumer) with three explicit decision branches (accept/counter/refuse) and a stop-and-reset smells checklist; checkpoints are present though validation is framed as 'tests run' rather than explicit pass/fail gates.	4 / 5
Progressive Disclosure	Well-sectioned with headers and a diagram, but it is a single ~330-line monolithic SKILL.md with no bundle files in references/scripts/assets and no one-level-deep references; material like the full worked-example table and the subagent brief could live in separate files.	3 / 5
	Total	13 / 20 Passed

Description

56%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 is specific and distinct about its niche (cross-SDK seam discipline), but it reads as a rationale rather than a discovery trigger: it omits an explicit 'Use when...' clause and lacks the natural phrases a user would say when reaching for the skill.

Suggestions

Add an explicit 'Use when...' clause naming the situations that should trigger this skill (e.g. 'Use when editing a contract where you own both sides of a boundary in one repo').

Lead with concrete trigger phrases a user would naturally say ('the two sides share a repo', 'we control both ends', 'crate + its WASM binding') rather than opening with the failure mode.

Tighten the opening so the concrete actions surface above the narrative framing.

Dimension	Reasoning	Score
Specificity	Names the domain (the seam between two SDKs) and several concrete actions — 'spawn an adversarial subagent profiled as the producer's maintainer', 'negotiate the change as a feature request, not a PR' — but the actions are procedural/discipline-oriented rather than a comprehensive list of capabilities.	4 / 5
Completeness	The 'what' is clearly stated (a discipline for the seam between two same-hand SDKs), but there is no explicit 'Use when...' / 'when should Claude use it' clause; the 'when' is only weakly implied by the failure-mode framing.	3 / 5
Trigger Term Quality	Relevant terms appear ('SDK', 'FFI', 'IPC', 'network protocol', 'Rust crate + WASM binding', 'wire format') but it lacks the natural, quotable phrases a user would actually say when reaching for this skill, and 'Use when...' guidance is absent.	3 / 5
Distinctiveness Conflict Risk	It carves a clear niche ('the seam the same author writes both sides of', 'companion to $sdk-design') that is largely distinct from generic design skills; minor overlap risk with $sdk-design, which it explicitly defers to.	4 / 5
	Total	14 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 1 suspicious	Warning

	Total	15 / 16 Passed

Repository: gridaco/grida
Path: .agents/skills/sdk-seam/SKILL.md
Commit: 8ef5e53

Reviewed: about 11 hours 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.