Index of every page on this site: llms.txt
All skills
macro-inc avatar

/add-sdk-endpoint

@3e0a52a
by Macromacro-inc/macro6.4k stars
606
Run it yourself

Wrap a new backend endpoint in the TypeScript SDK (packages/sdk), or record it as skipped. Use when `just coverage` fails, or after adding an endpoint to a Rust service.

Use this Skill: https://skilld.dev/gh/macro-inc/macro/add-sdk-endpoint

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈47 tokens for metadata: the name and description. ≈1.1k when used: this file.

Description uses 2.4% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈188 characters, or 2.4%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Add an SDK endpoint

Arg skip: record the endpoint as skipped instead of wrapping it. Run everything from packages/sdk.

Every generated endpoint must either have a call site under src/ or be listed in src/coverage/skipped.ts. Being in both also fails.

0. Find it

After a local Rust API change, regenerate its web contract from the repository root with bun run --cwd apps/web gen-api <service-name> before running bun run sync-specs && bun run generate here.

just coverage lists UNCOVERED <service>.<endpoint>.

A wrapped endpoint also needs a verb in src/utils/verbs.ts, from the closed SdkVerb set: what it does to a resource (edited), or read, listed, searched, queried or checked when it changes nothing, including a POST that only reads. just coverage fails on a wrapped method with no verb or a verb for a method that no longer exists. Don't grow the set; pick the closest.

1. Skip or wrap?

With the skip arg, skip. Otherwise ask the user, one line per endpoint, with a short recommendation — don't decide silently.

Skip-worthy: internal plumbing (auth/session, health, infra, web-app internals, MCP, batch previews) and features so narrow that no SDK user would reach for them. Everything a user could plausibly want belongs in the SDK.

To skip: add the method name, alphabetically, to <camelService>Excluded in src/coverage/skipped.ts, then just coverage && just check. Don't wrap.

To wrap it

  1. Read the method in generated/<service>/sdk.gen.ts and its types in types.gen.ts (note path / query / body).
  2. Pick a home, and read a sibling first — entities/tasks/ is the smallest complete example, entities/documents/document.ts the richest:
    • acts on one entity → method on that class
    • create/list/search/lookup → the namespace
    • new noun → new src/entities/<noun>/ pair, registered in src/macro.ts
    • cross-entity capability → a base in src/entities/entity.ts
  3. Never take or return a raw id (the SDK rule). Take the entity handle and return handles; if the noun has no entity class yet, build it in this change rather than accepting a string.
  4. Match the conventions:
    • static byId(client, id); detail via Lazy + protected fetch(), exposed with this.field(...) / this.mappedField(...)
    • extend MacroEntity / FavoritableEntity / PropertiedEntity, setting entityType / propertyEntityType
    • writes touching this entity's detail → this.mutate(...); others → unwrap(...)
    • every generated call goes through unwrap()
    • cursor lists → paginate() → AsyncGenerator; search → entitySearch(...)
    • camelCase + undefined on the SDK side even when the wire is snake_case/nullable
    • TSDoc every public member. No any. End each public method's TSDoc with its MCP hint tag (@readonly, @write, @send, @destructive; packages/sdk-mcp/AGENTS.md) and update that package's tool snapshots (bunx vitest run -u there).
    • an entity with its own page in the app gets webUrl(), built from this.client.webAppUrl and the route the web app's copy-link action uses (/app/agent/<id>, not the entity type when they differ), plus a toJSON() override adding url: this.webUrl(). Agents hand these links to users; without one they guess the route.
  5. New service? Only when the endpoint's service isn't reachable from MacroClient yet — per service, not per entity; a new entity needs none of this. Wire the Sdk into src/utils/client.ts, a host into src/config.ts, and an entry into ACCESSORS in src/coverage/check.ts. That last one is easy to miss: coverage decides "is this called?" by grepping src/ for the literal text .<accessor>.<endpoint>(, so a service absent from ACCESSORS reports every one of its endpoints as UNCOVERED no matter how well you wrapped them. If a whole service looks uncovered, check that map before believing it.
  6. Already listed as skipped? Remove it, or coverage fails with STALE SKIP.
  7. Verify: just check && just coverage && bun run lint && bun run format.
  8. Document: README only for genuinely new user-facing capability. New webhook events come from the storage spec via src/events/types.ts — regenerate, never hand-write.

Never

  • Hand-edit generated/ or specs/ — build output.
  • Accept an id where an entity handle belongs.
  • Mark something skipped just to make coverage pass.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts20d3 checks · Risk SAFE
  • Gen Agent Trust Hub20d

    This skill provides developer instructions for maintaining a TypeScript SDK. It outlines standard procedures for wrapping backend endpoints using local development tools like bun and just. No security risks or malicious patterns were detected.

  • Socket20d

    No alerts

  • Snyk20d

    Risk: LOW · No issues

Signed by skilld at 3e0a52a. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last week
What it can do
Runs commands Reads files Edits files
All 6 allowed tools
BashReadEditWriteGrepGlob

README badge

README badge for macro-inc/macro/add-sdk-endpoint