new-module
Add a feature module under modules/ with its service, routes, models, jobs, tools, migration, tests and docs registered in every place the platform looks. Use when adding a module or a large feature t
SKILL.md.agents/skills/new-module/SKILL.md
GitHubRead docs/writing-a-module.md first; it is the source of truth. Copy the shape of modules/feeds/ (officer routes) or modules/runpod/ (machine-token routes).
Steps:
modules/<name>/service.py: logic only. Takes a session and plain values, never imports Flask, raises a subclass ofcore.errors.ServiceError(message, status). Declare machine token scopes withmodules.auth.scopes.declareand org secrets withcore.secrets.declareordeclare_prefixat the top.models.py: tables oncore.db.Basewithname: Mapped[type] = mapped_column(...)columns,organization_idon every org-owned row, a unique constraint on the natural key.api.py: a blueprint. Useofficer_routeormachine_routefrommodules/auth/routes.pywithfunctools.partial. Views return a dict or(dict, status).jobs.pywith@jobfromcore/jobs.pyfor scheduled or background work. Import the service inside the function.tools.pywith@toolfromcore/tools.pywhen agents call the module, named<module>.<action>. No try/except:ServiceErrorbecomes a tool error. Add aSKILL.mdfor agents with frontmattername(the tool prefix) anddescription;tests/test_module_layout.pychecks it.- Register:
MOUNTSinmodules/registry.py, with the blueprint import at the top of the file.MODEL_MODULES,JOB_MODULESandTOOL_MODULESinmodules/manifest.py, for each of those files the module has.- Each Flask-free file other than
service.py,models.py,jobs.pyandtools.pyin the Flask-free contract inpyproject.toml. Those four are in it by wildcard. - If orgs can switch it off:
OPTIONAL_MODULESinmodules/organizations/service.py;module=on theMountand on each@tool; amodule_enabledcheck in jobs that run for all orgs. See "Org switch" indocs/writing-a-module.md.
- Migration: see the
migrationskill. - Tests in
tests/contract/test_<name>.py. Fake every network call by monkeypatching the module's fetch or client function. Add the module to the expected list intests/contract/test_modules.pywhen it is switchable. Add the new routes totests/contract/routes.txtwithUPDATE_ROUTES=1 uv run pytest tests/contract/test_routes.py. - Docs:
modules/<name>/README.mdwith a Files table and a Surface list, 25 lines or fewer; a row inmodules/README.mdand the README module table; the modules line inAGENTS.md; each new table indocs/data-model.md. If the module needs more than its README:docs/modules/<name>.md, a row indocs/README.md, and the page insite/scripts/sync-docs.ts. - Run
uv run pytest tests/test_module_layout.py. It names each place that you did not register the module. Then run thecheckskill.
Write comments and docs with the technical-writing skill.