ark-sdk-development

Regenerate and debug types across the ARK stack (SDK, API, Dashboard). Use when fixing TypeScript type errors in ark-dashboard, updating types after CRD changes, regenerating types.ts from OpenAPI spec, debugging "Property does not exist on type" schema errors, or adding custom SDK functionality via overlays. Covers the full type pipeline from Kubernetes CRDs to TypeScript.

1.05x

Quality

91%

Does it follow best practices?

Impact

100%

1.05x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Quality

Content

90%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 content is a lean, highly actionable guide: concrete build commands for every pipeline stage, a real troubleshooting loop for the common type error, and project-specific gotchas (Pydantic naming collisions) documented with a build-time safety net. The main gaps are a missing verification step after SDK generation and no use of bundle reference files to keep SKILL.md itself minimal.

Suggestions

Add an explicit verification step after "make ark-sdk-build" (e.g., import the generated types or run the SDK's tests) to close the validation gap in the main pipeline.

Move the Pydantic naming convention table and the deep-dive on schema-name collisions into a references/ file, keeping SKILL.md as a lean overview with a one-level-deep link.

Include an explicit regenerate-then-verify loop in the ark-dashboard section (generate:api → build → fix if errors → re-run) mirroring the debugging section's feedback pattern.

Dimension	Reasoning	Score
Conciseness	The body is commands, tables, and project-specific non-obvious knowledge (the Pydantic naming collision mechanism) with no padding and no explanation of concepts Claude already knows; every section earns its place, matching the lean anchor-5 example.	5 / 5
Actionability	Fully executable guidance throughout: "make ark-sdk-build", "make ark-api-build", "cd services/ark-dashboard/ark-dashboard; cp ../../ark-api/openapi.json ../out/; npm run generate:api; npm run build", and a concrete "grep" command for finding schema names, plus a copy-paste-ready naming table.	5 / 5
Workflow Clarity	The pipeline diagram plus per-stage sections give a clear sequence with several checkpoints ("npm run build # verify types compile", the generate_openapi.py collision safety net, and a regenerate → grep → fix debugging loop), but there is no verification step after "make ark-sdk-build" and the main pipeline lacks an explicit regenerate-then-verify loop — minor validation gaps fitting anchor 4 rather than anchor 5.	4 / 5
Progressive Disclosure	No bundle files exist; the single SKILL.md is well-sectioned with a Key Files table and a single one-level external issue link. It exceeds the under-50-lines simple-skill case (~110 lines) and content like the naming convention or debugging guide could live in reference files, so anchor 4 (good structure, minor organization gaps) fits better than anchor 5.	4 / 5
	Total	18 / 20 Passed

Description

92%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 strong: it states concrete capabilities across the full type pipeline, provides an explicit 'Use when...' clause with realistic trigger phrases including the literal compiler error message, and is tightly scoped to the ARK stack. Its only weakness is trigger vocabulary that leans on project-internal jargon rather than the broader set of natural phrasings a user might say.

Suggestions

Add a few natural user phrasings as triggers (e.g., "types are out of date", "type generation", "schema mismatch between Python and TypeScript") alongside the project-specific terms.

Spell out one or two generic-domain synonyms (e.g., "OpenAPI spec / openapi.json") so the description triggers even when the user omits ARK-specific vocabulary.

Dimension	Reasoning	Score
Specificity	"Regenerate and debug types", "regenerating types.ts from OpenAPI spec", "updating types after CRD changes", and "adding custom SDK functionality via overlays" list multiple specific concrete actions with comprehensive coverage of the type pipeline, matching the anchor-5 example rather than anchor 4's 'minor gaps'.	5 / 5
Completeness	Explicitly answers both: what ("Regenerate and debug types across the ARK stack (SDK, API, Dashboard)") and when ("Use when fixing TypeScript type errors... updating types after CRD changes...") with concrete trigger phrases, matching anchor 5.	5 / 5
Trigger Term Quality	Strong natural triggers including the literal error message "Property does not exist on type", "TypeScript type errors", "types.ts", and "CRD changes", but it relies on project-internal jargon and misses common variations like "types out of date" or "type generation", fitting anchor 4 (good coverage, a few natural terms missing) rather than anchor 5's comprehensive synonym coverage.	4 / 5
Distinctiveness Conflict Risk	ARK-specific naming ("ark-dashboard", "ARK stack", "types.ts", "overlays", "Kubernetes CRDs") carves out a clear niche with distinct triggers and minimal conflict risk; even the broadest trigger ("TypeScript type errors") is bound to ark-dashboard.	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: mckinsey/agents-at-scale-ark
Path: .claude/skills/ark-sdk-development/SKILL.md
Commit: d929af7

Reviewed: 3 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.