mockapi

Use this skill to create stateful mock API servers from OpenAPI contracts. The agent owns behavior analysis and sidecar authoring; bundled scripts only perform structural validation and deterministic typed scaffolding. Generated operation services are TODOs; the agent completes wiring and behavior from .mockapi/behavior.md anchors.

Command Router

Route invocations:

1. No argument: show a short menu with profile, generate, and freeform

examples. Ask what the user wants to do.

1. First word profile: read reference/profile.md and follow that workflow.

Everything after profile is the target or context.

1. First word generate: before any OpenAPI search or repo-wide file scan,

read reference/generate.md and run the generate sidecar preflight from that workflow. Everything after generate is the target or context. After the profile and sidecars are present and validation succeeds, always run <python> <skill-root>/scripts/generate.py; do not satisfy a generate command by only describing, planning, or hand-writing the scaffold.

1. Any other first word: treat the entire argument as a general mockapi request.

Do not reject unknown first words merely because they are not commands.

General mockapi request routing:

• Mock-server creation requests such as "make", "build", "create", "generate",

"scaffold", or "use this OpenAPI" route to reference/generate.md. generate auto-runs the profile workflow when sidecars are missing.

• Profile, analyze, describe, or sidecar-only requests route to

reference/profile.md.

• Validate, check, repair, or diagnose sidecar requests run

scripts/validate_profile.py, read reference/sidecars.md, and repair or report blockers as needed. The validator checks profile.toml and behavior.md unless --profile-only is used.

• Questions about existing generated mock-server code read

reference/generated-server.md, reference/mock-server-structure.md, and reference/mock-server-examples.md, then inspect the relevant files. When finishing or reviewing LLM-owned generated server code, also read reference/mock-server-quality.md.

If the freeform intent remains ambiguous after inspecting the repository, ask one concise clarification before mutating files. Do not invent extra commands or run unbundled scripts.

Runtime Rules

• Requires Python 3.11+ for bundled scripts. Resolve <python> to an

executable whose version is 3.11+ before running script examples. If no suitable interpreter exists, stop and report the requirement to the user. Bundled CLI scripts also verify the active interpreter and fail with a clear error when it is too old.

• Resolve <skill-root> to the directory containing this SKILL.md. Run shell

command examples by replacing <skill-root> with that absolute or repository-relative skill directory.

• Run only committed bundled Python scripts from scripts/*.py during normal

skill usage.

• Treat reference/*.md and the target repository context as the primary

contract for agent decisions. Do not read script source as a source of profiling requirements during normal profile work.

• Use reference/sidecars.md as the authoritative sidecar schema, including

valid profile.toml fields. If a needed sidecar shape is missing from the references, stop and report the exact documentation gap instead of inferring it from scripts/mockapi_runtime/*.py.

• Inspect bundled Python source only to diagnose a validator or generator defect

after running the committed scripts. Do not use script source to discover valid sidecar fields, defaults, or profile behavior policy.

• Do not run dependency installation inside the skill folder.
• For generated package dependency/script steps, use

scripts/detect_package_manager.py; do not hand-roll command -v package manager checks or rely on interactive shell startup files.

• In generate workflows, run generated package codegen before implementing or

editing LLM-owned controller wiring or feature modules.

• Do not edit OpenAPI contracts unless the user explicitly requests contract

changes.

• Treat .mockapi/profile.toml and .mockapi/behavior.md as the durable

source of truth for generation.

• For any generate workflow, run scripts/generate.py --run-codegen after

successful validation. If validation fails, repair sidecars or report blockers instead of running the generator on invalid data.

• Treat profile.toml as the structural operation index. Implement operation

behavior from the matching behavior.md anchor, not from operation shape.

• Use reference/sidecars.md for sidecar shape and validation expectations.
• Use reference/generated-server.md, reference/mock-server-structure.md,

reference/mock-server-examples.md, reference/seed-data.md, reference/testing.md, and reference/mock-server-quality.md when inspecting or finishing generated server code.

Bundled Scripts

Validate sidecars:

<python> <skill-root>/scripts/validate_profile.py

Preflight sidecars for generate:

<python> <skill-root>/scripts/preflight_generate.py --root .

Profile-only validation:

<python> <skill-root>/scripts/validate_profile.py --profile-only

Generate server scaffold and run codegen:

<python> <skill-root>/scripts/generate.py --root . --profile .mockapi/profile.toml --run-codegen

Detect generated package manager for manual regeneration:

<python> <skill-root>/scripts/detect_package_manager.py --root . --profile .mockapi/profile.toml

Final quality gate after implementation only:

<python> <skill-root>/scripts/check_generated_quality.py --package-root <packageRoot> --profile .mockapi/profile.toml