agentleFS
beydemirfurkanbeydemirfurkan/todox/.claude/skills/add-rpc-method/SKILL.md

add-rpc-method

Skill2 starsChanged 59 days agoMITView on GitHub

Use when adding, renaming or removing a todox RPC method or MCP tool — anything an agent can call. Covers the order the six files have to be touched in, and what breaks when one is missed.

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every agent-facing capability is the same six-file change.

    line 8
  2. Very specific:

    Add the parameter shape to SHAPES.

    line 13
  3. Very specific:

    If the method is a patch, add a .refine() next to updateTask / updateProject requiring at least one field.

    line 21
  4. Very specific:

    Add it to methods. The object is satisfies Record<MethodName, …> and MethodName comes from the keys of SHAPES, so a handler without a …

    line 31
  5. Very specific:

    If the tool changes what an agent should do at session start or before finishing, update BASE in the same file — and if the advice differs …

    line 67

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Adding an RPC method

Every agent-facing capability is the same six-file change. The order matters: the schema is the contract, and the handler will not compile without it.

1. Schema — lib/services/rpc-schemas.ts

Add the parameter shape to SHAPES. This is the runtime contract and the MCP tool surface: mcp/server.ts imports the same object, so a tool cannot advertise an argument the server rejects.

  • .describe() text is read by a model deciding whether to call the tool. Write it for that reader, not for a human skimming types.
  • Objects are built .strict() in OBJECTS, so unknown keys are an error rather than something a repository has to defend against.
  • If the method is a patch, add a .refine() next to updateTask / updateProject requiring at least one field. A patch of nothing used to return the unchanged row, which reads to an agent exactly like a success.
  • Fields a local process can fill in itself (repo_root, tz) go in the schema and are hidden from the model only in local mode (LOCAL_INTERNAL in mcp/tools.ts). Hosted, nobody but the agent knows them, so they are advertised and the .describe() text has to tell it what to send.

2. Handler — lib/services/rpc.ts

Add it to methods. The object is satisfies Record<MethodName, …> and MethodName comes from the keys of SHAPES, so a handler without a schema is a compile error — that is the guardrail, keep it.

The handler signature is TypeScript and is erased at build time. It guards nothing. Validation happened in step 1.

3. Where the work lives

  • One table → a repository in lib/repositories/.
  • More than one table, or anything that must stay consistent across tables (a status change writing a task_events row) → lib/services/.
  • Repositories never call each other.
  • Ownership is asserted in exactly one place: lib/services/ownership.ts. Do not inline WHERE user_id = ? at the call site. A row belonging to somebody else answers 404, never 403.

4. Tool registration — mcp/tools.ts (both transports)

One definition serves the hosted endpoint (app/api/mcp/route.ts) and the stdio process (mcp/server.ts). Register with the tool() helper; it pulls the input schema from SHAPES, so do not restate it. Use the options when the model should not be filling something in itself:

  • overrides — advertise a friendlier shape (create_task takes plain paths and this side attaches the hashes; a model cannot invent a sha256).
  • prepare — last chance to add what only this side knows.
  • after — runs on the result and may call back (checkLinkedFiles).
  • transform / presentation — rendering that belongs on this side.

Anything that needs a disk goes through Workspace — hash, repoRoot, tz, checkRefs. The hosted server answers all of them with null/undefined and the tool must degrade, not fail: record what it was given and let the status fall to unknown. Never let one side claim a file is unchanged when it could not read it.

If the tool changes what an agent should do at session start or before finishing, update BASE in the same file — and if the advice differs by mode, LOCAL_NOTE / REMOTE_NOTE.

5. README

README.md has a table of tools under "Connect an agent". A tool that is not in it does not exist as far as a reader is concerned.

6. Test

lib/services/rpc-schemas.test.ts — assert the params that must be rejected. These tests need no database, so they run in CI on every push.

pnpm smoke:mcp runs the whole agent surface through both transports against a live server. If a tool only works one way in, that is where it shows.

Before you call it done

pnpm lint && pnpm test && pnpm build && pnpm exec tsc --noEmit

tsc --noEmit is the one that covers mcp/ and scripts/; the build does not.

The rules above are the short version of CONTRIBUTING.md.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.