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:
- No argument: show a short menu with
profile, generate, and freeform
examples. Ask what the user wants to do.
- First word
profile: read reference/profile.md and follow that workflow.
Everything after profile is the target or context.
- 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.
- 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
1---2name: mockapi3description: Create stateful TypeScript/Hono mock API servers from OpenAPI 3.0/3.1 contracts. Use for building OpenAPI-based mock APIs, creating or repairing .mockapi sidecars, validating mock profiles, generating admin state endpoints, or freeform requests such as "mockapi build a mock server for api/openapi.yaml".4metadata:5 source: https://skillmd.com/skills/devctllabs/mockapi6---78# mockapi910Use this skill to create stateful mock API servers from OpenAPI contracts. The11agent owns behavior analysis and sidecar authoring; bundled scripts only perform12structural validation and deterministic typed scaffolding. Generated operation13services are TODOs; the agent completes wiring and behavior from14`.mockapi/behavior.md` anchors.1516## Command Router1718Route invocations:19201. No argument: show a short menu with `profile`, `generate`, and freeform21 examples. Ask what the user wants to do.222. First word `profile`: read `reference/profile.md` and follow that workflow.23 Everything after `profile` is the target or context.243. First word `generate`: before any OpenAPI search or repo-wide file scan,25 read `reference/generate.md` and run the generate sidecar preflight from26 that workflow. Everything after `generate` is the target or context. After27 the profile and sidecars are present and validation succeeds, always run28 `<python> <skill-root>/scripts/generate.py`; do not satisfy a `generate`29 command by only describing, planning, or hand-writing the scaffold.304. Any other first word: treat the entire argument as a general mockapi request.31 Do not reject unknown first words merely because they are not commands.3233General mockapi request routing:3435- Mock-server creation requests such as "make", "build", "create", "generate",36 "scaffold", or "use this OpenAPI" route to `reference/generate.md`.37 `generate` auto-runs the profile workflow when sidecars are missing.38- Profile, analyze, describe, or sidecar-only requests route to39 `reference/profile.md`.40- Validate, check, repair, or diagnose sidecar requests run41 `scripts/validate_profile.py`, read `reference/sidecars.md`, and repair42 or report blockers as needed. The validator checks `profile.toml` and43 `behavior.md` unless `--profile-only` is used.44- Questions about existing generated mock-server code read45 `reference/generated-server.md`, `reference/mock-server-structure.md`, and46 `reference/mock-server-examples.md`, then inspect the relevant files. When47 finishing or reviewing LLM-owned generated server code, also read48 `reference/mock-server-quality.md`.4950If the freeform intent remains ambiguous after inspecting the repository, ask51one concise clarification before mutating files. Do not invent extra commands or52run unbundled scripts.5354## Runtime Rules5556- Requires Python 3.11+ for bundled scripts. Resolve `<python>` to an57 executable whose version is 3.11+ before running script examples. If no58 suitable interpreter exists, stop and report the requirement to the user.59 Bundled CLI scripts also verify the active interpreter and fail with a clear60 error when it is too old.61- Resolve `<skill-root>` to the directory containing this `SKILL.md`. Run shell62 command examples by replacing `<skill-root>` with that absolute or63 repository-relative skill directory.64- Run only committed bundled Python scripts from `scripts/*.py` during normal65 skill usage.66- Treat `reference/*.md` and the target repository context as the primary67 contract for agent decisions. Do not read script source as a source of68 profiling requirements during normal profile work.69- Use `reference/sidecars.md` as the authoritative sidecar schema, including70 valid `profile.toml` fields. If a needed sidecar shape is missing from the71 references, stop and report the exact documentation gap instead of inferring72 it from `scripts/mockapi_runtime/*.py`.73- Inspect bundled Python source only to diagnose a validator or generator defect74 after running the committed scripts. Do not use script source to discover75 valid sidecar fields, defaults, or profile behavior policy.76- Do not run dependency installation inside the skill folder.77- For generated package dependency/script steps, use78 `scripts/detect_package_manager.py`; do not hand-roll `command -v` package79 manager checks or rely on interactive shell startup files.80- In `generate` workflows, run generated package codegen before implementing or81 editing LLM-owned controller wiring or feature modules.82- Do not edit OpenAPI contracts unless the user explicitly requests contract83 changes.84- Treat `.mockapi/profile.toml` and `.mockapi/behavior.md` as the durable85 source of truth for generation.86- For any `generate` workflow, run `scripts/generate.py --run-codegen` after87 successful validation. If validation fails, repair sidecars or report blockers88 instead of running the generator on invalid data.89- Treat `profile.toml` as the structural operation index. Implement operation90 behavior from the matching `behavior.md` anchor, not from operation shape.91- Use `reference/sidecars.md` for sidecar shape and validation expectations.92- Use `reference/generated-server.md`, `reference/mock-server-structure.md`,93 `reference/mock-server-examples.md`, `reference/seed-data.md`,94 `reference/testing.md`, and `reference/mock-server-quality.md` when95 inspecting or finishing generated server code.9697## Bundled Scripts9899Validate sidecars:100101```bash102<python> <skill-root>/scripts/validate_profile.py103```104105Preflight sidecars for generate:106107```bash108<python> <skill-root>/scripts/preflight_generate.py --root .109```110111Profile-only validation:112113```bash114<python> <skill-root>/scripts/validate_profile.py --profile-only115```116117Generate server scaffold and run codegen:118119```bash120<python> <skill-root>/scripts/generate.py --root . --profile .mockapi/profile.toml --run-codegen121```122123Detect generated package manager for manual regeneration:124125```bash126<python> <skill-root>/scripts/detect_package_manager.py --root . --profile .mockapi/profile.toml127```128129Final quality gate after implementation only:130131```bash132<python> <skill-root>/scripts/check_generated_quality.py --package-root <packageRoot> --profile .mockapi/profile.toml133```