CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

add-rest-endpoint

Add or wire a REST data-plane endpoint (GET or POST /api/v1/*) in this repo — the curl-able passthrough surface documented in docs/REST_ENDPOINTS.md. Adds the entry to src/restCatalog.ts (the single source of truth), registers the Express handler in src/website/webServer.ts with the right service auth middleware, adds the auth-gate test, and regenerates docs/REST_ENDPOINTS.md + public/openapi.json + docs/MCP_TOOLS.md. Use whenever the user wants to add, wire, expose, or promote a REST endpoint, give an MCP tool a curl/HTTP sibling, flip a `planned` catalog entry to `live`, ship the whole REST surface for a service, or expose a write/mutation tool over HTTP POST. Also invoked automatically by `add-mcp-server` (its step 6e) to wire a newly scaffolded service's endpoints, which ship as their own pull request. Also use when invoked as `/add-rest-endpoint <mcpToolName|service> [service]`.

Quality

91%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Critical

Do not install without reviewing

SKILL.md
Quality
Evals
Security

Quality

Content

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

An exceptionally actionable, well-sequenced procedure for a genuinely complex multi-file task — every step has executable commands, exact formats, validation checkpoints, and hard-won repo-specific gotchas, with reference and template files that all exist and are clearly signaled. Its weakness is length: repeated rules, environment-war-story failure modes, and narrative incident retellings that could be condensed or moved into the references leave it tighter-than-ideal on token efficiency and keep SKILL.md heavier than a lean overview.

Suggestions

State each cross-cutting rule once and cross-link it: the 'own PR' shipping rule and the scaffold-registration requirement are each explained in three places (step 8 / Batch mode / One pass, one PR and step 2 / Batch mode / Relationship to other skills respectively) — keep the fullest statement and replace the others with a one-line pointer.

Move the two environment-specific failure modes (the Redis hang in the test suite and the data/mcp-connections.json corruption race) to a shared testing reference or the repo's root docs; they are not REST-endpoint-specific and add tokens unrelated to this skill's scope.

Condense the Pinecone namespace narrative in step 4 to the resulting rules ('read identifier constraints from the provider spec, put conversions at a single wire boundary') with a one-line justification, moving the full incident to a reference if it needs to be preserved.

DimensionReasoningScore

Conciseness

The body is dense with genuinely non-derivable repo knowledge (parser-regex field order, the createServiceAuth provider-switch gotcha), but several things are stated multiple times — the own-PR rule appears in the step 8 report template, Batch mode, and its own section; the scaffold-registration requirement appears in step 2, Batch mode, and the Relationships section — and two failure modes ('Tests that pass but never EXIT', 'data/*.json grows without bound') describe the general test environment, not REST endpoints. This fits the 3 anchor ('mostly efficient but includes some unnecessary explanation or could be tightened') better than the 4 anchor, where over-explanation would be only minor.

3 / 5

Actionability

Guidance is copy-paste ready throughout: the exact catalog entry line with field order, grep and python one-liners for route and operationId checks, the three regeneration commands, a full report template, and real template files (assets/templates/{google,third-party,write}-route.ts.tmpl) to generate handlers from. This matches the 5 anchor ('fully executable; copy-paste ready code or commands; specific examples cover the common cases').

5 / 5

Workflow Clarity

An 8-step procedure with a four-way classification up front, explicit validation checkpoints with feedback loops (step 7: 'if your endpoint isn't in it, the catalog line broke the parser regex'; coverage measured at 80%+ lines and branches), sign-off gates for destructive writes, and a Failure modes checklist for error recovery. This is the 5 anchor — clear sequence, explicit validation, feedback loops, and a checklist for a complex batch-capable process.

5 / 5

Progressive Disclosure

The bundle split is sound and real: 'This SKILL.md is the procedure; references/route-pattern.md is the canonical handler shape; references/write-endpoints.md covers the write-specific rules' — all files exist, are one level deep, clearly signaled, and documented in a File layout tree. However, the ~370-line SKILL.md carries more than an overview's worth of detail that could live in references (the batch-mode table pattern, the git-merge verification recipe, the Pinecone incident narrative), which fits the 4 anchor ('most content is appropriately placed; minor organization gaps') rather than the 5 anchor's lean overview.

4 / 5

Total

17

/

20

Passed

Description

100%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 model description: it states precisely what files the skill changes, gives an explicit and varied 'Use whenever...' trigger clause covering direct invocation, chaining from add-mcp-server, and slash-command use, and is unmistakably distinct from neighboring skills. Every clause carries capability or trigger information rather than padding, so its length is justified.

DimensionReasoningScore

Specificity

The description lists multiple specific concrete actions with exact file targets — 'Adds the entry to src/restCatalog.ts (the single source of truth), registers the Express handler in src/website/webServer.ts with the right service auth middleware, adds the auth-gate test, and regenerates docs/REST_ENDPOINTS.md + public/openapi.json + docs/MCP_TOOLS.md' — comprehensive coverage of everything the skill touches. This matches the 5 anchor ('multiple specific concrete actions; comprehensive coverage') and exceeds the 4 anchor, which allows coverage gaps; none are evident.

5 / 5

Completeness

Both halves are explicit: the 'what' enumerates the five concrete file changes, and the 'when' is a dedicated clause — 'Use whenever the user wants to add, wire, expose, or promote a REST endpoint...' plus chaining and slash-command invocation contexts. This is the 5 anchor ('clearly and explicitly answers both what AND when with concrete trigger phrases'), not the 4 anchor where the 'when' is present but could be more specific.

5 / 5

Trigger Term Quality

Trigger phrasing is comprehensive with natural synonyms: 'add, wire, expose, or promote a REST endpoint', 'give an MCP tool a curl/HTTP sibling', "flip a `planned` catalog entry to `live`", 'ship the whole REST surface for a service', 'expose a write/mutation tool over HTTP POST'. These are the phrases a user would naturally say; no common variation is missing, matching the 5 anchor rather than the 4 anchor ('a few natural terms missing').

5 / 5

Distinctiveness Conflict Risk

The niche is sharply bounded to this repo's '/api/v1/*' curl-able passthrough surface, and it explicitly disambiguates against sibling skills ('Also invoked automatically by `add-mcp-server` (its step 6e)'), with the body further separating add-mcp-tool and update-openapi. Clear niche with distinct triggers and minimal conflict risk — the 5 anchor.

5 / 5

Total

20

/

20

Passed

Validation

87%

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

Validation — 14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

metadata_version

'metadata.version' is missing

Warning

referenced_paths_exist

Referenced path issues: 4 possibly missing (references/scaffold-rules.md, scripts/buildMcpToolsDoc.mjs, scripts/buildRestEndpointsDoc.mjs, scripts/buildRootOpenapi.mjs), 3 deeper-than-1-level

Warning

Total

14

/

16

Passed

Repository

boarlabsxyz/awesome-mcp

Path

.claude/skills/add-rest-endpoint/SKILL.md

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.