Claude Skill Test Data Generation: Teaching Claude the JsonFabrica Workflow

Claude Skill test data generation doesn't work by exposing new tools Claude can call — it works by handing Claude a markdown file it reads before attempting the task. JsonFabrica ships an Agent Skill, jsonfabrica-skill: a SKILL.md entry point plus four resource files that teach Claude the correct JsonFabrica workflow, including a handful of mistakes agents reliably make without it. It's a companion to JsonFabrica's MCP server, not a replacement for it — this post is about the Skill mechanism itself and what it teaches, not about tool-calling.

What's actually in the JsonFabrica Agent Skill

The whole thing is five files, all plain markdown:

jsonfabrica-skill/
  SKILL.md
  resources/
    mcp-tool-reference.md
    function-catalog.md
    rest-api-quickstart.md
    examples.md

SKILL.md opens with a YAML frontmatter block — just name: jsonfabrica and a description — followed by a body covering JsonFabrica's core workflow and a short gotchas list. The four resources/ files are each scoped to one job: the full 24-tool MCP reference (grouped by area, with a "what do you want to do → which tool" lookup table), the full 25-function data-generation catalog, a curl-based REST quickstart for when no MCP tools are present, and worked end-to-end examples covering single documents, sequences, batches, ad hoc generation, and control flow. None of that detail lives in SKILL.md itself — it's linked from there and read only when the task at hand actually needs it.

How progressive disclosure keeps this cheap to have loaded

The reason a Skill is split into an always-short entry point and several only-sometimes-needed resource files is the same reason a good onboarding doc has a table of contents instead of one giant page: most tasks only need a fraction of the reference material, and loading all of it up front wastes context on every single turn, not just the ones that need it.

Concretely, in jsonfabrica-skill, that plays out in layers. The frontmatter description — a few sentences naming synthetic/mock/test JSON data, JsonFabrica templates, and jsonfabrica_* MCP tools — is the one piece a Claude client can inspect cheaply to decide whether this skill is even relevant to the current task, without reading anything else. If it decides yes, the SKILL.md body loads: the core workflow, inline examples, and gotchas, short enough to stay cheap on every task that touches JsonFabrica. The four resources/ files load only when SKILL.md links to one for a specific sub-task — writing a batch with relations, say, pulls in examples.md; looking up a function's exact signature pulls in function-catalog.md. A task that only needs one generated field never has to load either. Anthropic's own writeup on Agent Skills covers the general mechanism in more depth; what's described above is specifically how jsonfabrica-skill's own files are laid out to use it.

Claude Skill test data generation: the workflow it actually teaches

The core workflow in SKILL.md is short on purpose, and it's built around the mistakes an agent makes without it, not a generic API tour:

1. Confirm auth first — jsonfabrica_whoami / GET /v1/whoami returns { tenantId, role }; jsonfabrica_health / GET /health needs no auth for a pure connectivity check.
2. One-off or reusable? Throwaway exploration uses jsonfabrica_generate_adhoc / POST /v1/templates/generate — nothing is saved, but it still counts toward usage. Anything generated from more than once should be a saved template via jsonfabrica_create_template / POST /v1/templates.
3. Template body is a JSON string with <functionName(args)> placeholders inside it, not a JSON object with unquoted function syntax — and it must contain at least one placeholder, or generation is rejected outright.
4. Sequences need both halves. <createSeq(name, type?, start?, step?)> declares a counter and returns nothing; <getSeq(name)> is the call that actually returns the next value. This is the single most common thing the Skill exists to stop Claude from getting wrong — calling createSeq alone and expecting a usable value back.
5. Related documents go in one batch call, not N separate ones. jsonfabrica_create_batch / POST /v1/batches takes a documents array; a child entry's relations map (e.g. { "customerId": { "from": "customer.id", "strategy": "round-robin" } }) tells the batch engine to inject the parent's field onto each generated child document after generation. The child template body never calls a function to fetch it — that's the second recurring mistake the Skill heads off. round-robin is required, and is currently the only supported strategy, once a parent's count is greater than 1; batches can return 200 with results synchronously or 202 for a queued batch to poll.
6. Reproduce output with seed. Every generate response includes meta.seed; pass it back on a later call for identical output.
7. Reuse a value inside one template with getVar, not by recomputing or hardcoding it — nearly every function accepts an optional trailing variable-name argument for exactly this.

Agent Skills test data: with or without the MCP server

The one thing worth being precise about: this Skill is not a second way to integrate with JsonFabrica alongside the MCP server, competing with it for the same job. SKILL.md's own instructions are explicit — if jsonfabrica_* MCP tools are available in the session, always use them instead of hand-writing HTTP calls. The Skill only falls back to plain REST/curl, documented in resources/rest-api-quickstart.md, when no MCP tools are present or the user specifically wants HTTP client code.

What the Skill adds either way is the knowledge layer sitting above whichever transport is in use: the createSeq/getSeq split, the relations-map batch pattern, quoted-vs-unquoted placeholder typing, and which endpoints don't have an MCP tool at all (signup and billing-tier changes are deliberately excluded from the MCP server, by design, since they touch real subscriptions). An agent with only the MCP server installed still has to learn those gotchas by trial and error, one failed generate call at a time. An agent with the Skill installed reads them once, before it writes the first template.

Claude Code test data: getting the Skill into a session

jsonfabrica-skill is content only — a SKILL.md plus a resources/ folder, following the same file layout as any Agent Skill — so using it is a matter of putting that folder wherever your Claude client looks for skills, per your Claude Code or Claude Desktop version's own documentation for installing a local or repo-based skill. Pull it from the jsonfabrica-skill GitHub repository. It doesn't require the @jsonfabrica/mcp-server package to be installed alongside it, and it doesn't require a running MCP server at all if you're fine with Claude generating REST/curl calls directly against your API key.

FAQ

What is a Claude Agent Skill? An Agent Skill is a folder of markdown files, starting with a SKILL.md that has a YAML frontmatter description plus a body of instructions, that a Claude client reads to learn how to perform a specific task well. The short frontmatter description is always available so Claude can decide when the skill is relevant, and the fuller body and any linked resource files are only read once the skill actually activates.

How is the JsonFabrica Skill different from the JsonFabrica MCP server? The MCP server, @jsonfabrica/mcp-server, exposes jsonfabrica_* tools Claude can call directly to create templates, generate documents, and manage batches. The Skill is a markdown knowledge layer, not another set of callable tools: it teaches Claude the correct JsonFabrica workflow and common mistakes, and its own instructions say to use the MCP tools instead of hand-written HTTP calls whenever they're available in the session.

Do I need the MCP server installed to use the JsonFabrica Skill? No. The Skill works standalone by falling back to plain REST calls against the JsonFabrica API with an Authorization: Bearer header, documented in its rest-api-quickstart.md resource file. If jsonfabrica_* MCP tools are also present in the session, the Skill's own instructions say to prefer those over hand-written HTTP calls, but the Skill doesn't require the MCP server to be useful.

How do I install the JsonFabrica Agent Skill for Claude Code? The jsonfabrica-skill repository is a plain SKILL.md file plus a resources folder, following Anthropic's Agent Skills file layout, so it installs by placing that folder wherever your Claude client discovers skills from. Check the jsonfabrica-skill GitHub repository and your Claude Code or Claude Desktop documentation for the exact skills directory your version expects.

What mistakes does the JsonFabrica Skill specifically stop Claude from making? Two recurring ones: calling createSeq and expecting it to return a value, when createSeq only declares the counter and getSeq is what actually returns the next number, and writing a batch child template that tries to fetch a parent field with a function call, when parent-to-child linking in a batch is done with a relations map that injects the value after generation instead. The Skill also flags that quoting a placeholder inside a JSON string always produces a string result, even for numbers and booleans, unless the quotes are dropped.

Whether Claude reaches your JsonFabrica templates through MCP tool calls or plain REST requests, the underlying templates API is the same one behind both — the Skill just makes sure Claude gets the workflow right the first time instead of guessing at it.