Borrowing it
Nothing to install: this file belongs to agigante80/actual-mcp-server. Take a copy, put it at the same path in your own repository, and replace the rules that are about this project with yours.
curl -O https://raw.githubusercontent.com/agigante80/actual-mcp-server/main/.claude/skills/api-design-principles/SKILL.mdgit clone --depth 1 https://github.com/agigante80/actual-mcp-serverWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/skills/agigante80/actual-mcp-server/api-design-principles)<a href="https://agentmods.dev/skills/agigante80/actual-mcp-server/api-design-principles"><img src="https://agentmods.dev/badge/skills/agigante80/actual-mcp-server/api-design-principles/github.svg" alt="Measured on agentmods" height="20"></a>Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.
<a href="https://agentmods.dev/skills/agigante80/actual-mcp-server/api-design-principles"><img src="https://agentmods.dev/badge/skills/agigante80/actual-mcp-server/api-design-principles.svg" alt="Reviewed on agentmods" width="80" height="20"></a>- NVIDIA SkillSpector warn
SkillSpector: 1 finding, up to high
These are SkillSpector’s own severities. On a checked sample its high-severity flags on skills were ~96% false positives — a documented command, a public API, a “never do X” rule — so we show them as a caution to read, not a verdict. Why →
- high Tool Misuse · line 201 Tool parameters are crafted to achieve unintended or unsafe behavior. Parameter abuse can bypass intended safety checks (e.g. shell=True, --force, dangerous glob patterns).Fix: Validate all tool parameters against an allowlist. Reject dangerous parameter values (shell=True, --force, -rf /) and use safe defaults.
What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5.1 | $0.00075 | $0.05222 |
| Opus 5 | $0.00037 | $0.02611 |
| Sonnet 5 | $0.00015 | $0.01044 |
| Haiku 4.5 | $0.00007 | $0.00522 |
Grade A, and why
api-design-principles scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 633 lines — stays where its author put it; the contents beside it link to each section on GitHub.
API Design Principles
Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.
When to Use This Skill
- Designing new REST or GraphQL APIs
- Refactoring existing APIs for better usability
- Establishing API design standards for your team
- Reviewing API specifications before implementation
- Migrating between API paradigms (REST to GraphQL, etc.)
- Creating developer-friendly API documentation
- Optimizing APIs for specific use cases (mobile, third-party integrations)
Applying this to actual-mcp-server (the project API is MCP tools)
This project exposes no REST or GraphQL surface: its "API" is the set of 71 MCP tools advertised over the HTTP and stdio transports. Read the generic REST/GraphQL sections below as the underlying principles, and apply them through these project rules (from CLAUDE.md):
- Resource-oriented naming maps to
actual_{domain}_{action}. The domain is the noun (accounts,transactions,budgets,payees,rules,schedules), the action is the verb (create,update,delete,list,get,search). Keep a new tool consistent with the existing names insrc/actualToolsManager.ts(IMPLEMENTED_TOOLS); a lone inconsistent verb is the tell that the design drifted. - The schema IS the contract. Every tool's input is a Zod object (prefer
createTool()fromsrc/lib/toolFactory.ts; reuse fields fromCommonSchemasinsrc/lib/schemas/common.ts). The published JSON Schema is what clients (and models) consume, so it must be self-describing and strict-client-safe: keep it ECMA-262/OpenAI-compatible (no\p{...}/\u{...}patterns, guarded bytests/unit/schema_json_openai_compat.test.js), and give every field a.describe(). - Types are fixed by convention, not per-tool invention. Amounts are always integer cents
(
5000= $50.00, never decimal dollars). Dates areYYYY-MM-DDstrings, neverDate.now(). IDs useCommonSchemas.<entity>Id, andtests/unit/tool_id_schema_drift.test.jsfails the build if an id-shaped field does not (#380). Note this line USED to be aspirational: when the guard was written, 33 of 41 id fields were on one of three looser forms (a barez.string(), a.min(1).max(64)bound, or an inlineUUID_PATTERNmeaning the identical thing), soaccounts_update.idwas published as a UUID whilecategories_update.idwas published as any string. A convention four fifths of the surface ignores is not a convention, which is why it is now enforced rather than stated.
What ships with it
4 files beside SKILL.md in the same directory: the scripts, references and assets a skill reads on demand. Not counted in the per-session cost; read them before you install if any of them is executable.
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 2d ago Changed 35838af8ce6f
- 5d ago Changed 6a504720b8e8
- 9d ago First seen · 633 lines · 75 tokens per session scan A 92339db78753
api-design-principles is a skill published in the GitHub repository agigante80/actual-mcp-server (51 stars, last pushed yesterday), licensed MIT. It adds 75 tokens to every session and 5,222 once invoked, about $0.0004 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
Other skills, from other repositories
add-dial-tool
Give chosen NanoClaw agents a real phone number as a container tool — the dial CLI baked into the agent image plus OneCLI credential injection for api.getdial.ai, scoped per agent, so the agents you pick can send SMS, place AI voice calls, and receive verification codes from inside the sandbox. Independent of the Dial…
add-signal
Add Signal channel integration via signal-cli device-link. Native adapter — no Chat SDK bridge.
add-matrix
Add Matrix channel integration via Chat SDK. Works with any Matrix homeserver.
add-gchat
Add Google Chat channel integration via Chat SDK.
onecli-gateway
OneCLI Gateway: transparent HTTPS proxy that injects stored credentials into outbound calls. You MUST use this skill when the user asks you to read emails, check calendar, access GitHub repos, create issues, check Stripe payments, or interact with ANY external service or API. Do NOT use browser extensions or OAuth CLI…
add-slack
Add Slack channel integration via Chat SDK.