Maintain Project API
Maintain canonical API.md files through one deterministic API-reference workflow.
This skill is the default baseline path for API.md maintenance across most repositories. Reach for a narrower plugin only when the target repo has a specialized shape that deserves its own maintainer contract, such as a skills-export or plugin-export repository.
Inputs
- Required:
--project-root <path>
- Required:
--run-mode <check-only|apply>
- Optional:
--api-path <path>
- Optional:
--config <path>
Workflow
- Validate the project root and resolve the target
API.md.
- Load the canonical API-reference schema from
config/api-customization.template.yaml, then merge any explicit override or project-local customization file.
- In
check-only, audit the required section schema, required subsection schema, required table of contents, placeholder content, and verification-command formatting.
- In
apply, keep edits bounded to the target API.md while creating a missing file from the bundled template and normalizing the document to the canonical structure.
- Re-run the same audit to confirm post-fix status.
Canonical Base Contract
The source of truth for the base API-reference contract lives in:
config/api-customization.template.yamlassets/API.template.md
The base contract requires:
- a top-level title and short summary
- a required
## Table of Contents
- canonical top-level sections for overview, API surface, authentication and access, requests and responses, errors, versioning and compatibility, local development and verification, and support ownership
- required subsection structure for the sections that need stable consumer-facing detail
Writing Expectations
Overview > Who This API Is For should name the real consumers: humans, services, tools, packages, apps, or maintainers.Overview > Stability Status should say whether the API is stable, experimental, internal, deprecated, or otherwise constrained.API Surface should list concrete entry points and the protocol, transport, runtime, package interface, or file format used to reach each one.Authentication and Access should describe credentials and permissions without inventing secrets, scopes, roles, or access paths.Requests and Responses should document grounded request inputs, response outputs, and data models.Errors should make failures actionable by documenting the error shape and common failure modes with likely causes or next checks.Versioning and Compatibility should make the supported compatibility window and breaking-change handling explicit.Local Development and Verification > Verification should prefer fenced commands or reproducible call examples with language info strings.Support and Ownership should name only grounded teams, maintainers, issue trackers, services, or escalation paths.
Codex Subagent Fit
When the user explicitly asks for subagents or parallel agent work, use subagents only for read-heavy API evidence gathering before the main workflow edits or reports. Good jobs include inventorying endpoints or public symbols, checking examples against tests, reading schema definitions, or comparing compatibility claims against release notes.
Keep apply edits in the main thread because this skill owns one target API.md file and must avoid invented endpoints, schemas, credentials, or support promises. Ask workers for concise evidence and file references instead of replacement API prose.
Output Contract
- Return Markdown plus JSON with:
run_contextschema_contractschema_violationscommand_integrity_issuescontent_quality_issuesfixes_appliedpost_fix_statuserrors
- If there are no issues and no errors, output exactly
No findings.
Guardrails
- Never auto-commit, auto-push, or open a PR.
- Never invent commands, endpoints, protocols, schemas, environment variables, credentials, permissions, version guarantees, support paths, or compatibility promises that are not grounded in the repo.
- Never edit files other than the target
API.md.
- Keep
API.md as the canonical API-reference filename for this skill.
- Treat this skill as a hard-enforced base template. Downstream plugins may specialize the schema, but the base skill should not do repo-profile inference.
References
agents/openai.yamlreferences/section-schema.mdreferences/output-contract.mdreferences/fix-policies.mdreferences/style-rules.mdreferences/api-customization.mdreferences/api-config-schema.mdreferences/project-api-maintenance-automation-prompts.md
1---2name: maintain-project-api3description: Maintain canonical API.md files through deterministic audit and bounded apply modes. Use when a project API reference needs auditing, normalization, or bounded fixes for API surface, authentication, request and response schemas, errors, versioning, compatibility, local verification, or support guidance. This is the default baseline API.md workflow for most repos unless a narrower plugin owns that repo shape.4---5
6# Maintain Project API
7
8Maintain canonical `API.md` files through one deterministic API-reference workflow.
9
10This skill is the default baseline path for `API.md` maintenance across most repositories. Reach for a narrower plugin only when the target repo has a specialized shape that deserves its own maintainer contract, such as a skills-export or plugin-export repository.
11
12## Inputs
13
14- Required: `--project-root <path>`
15- Required: `--run-mode <check-only|apply>`
16- Optional: `--api-path <path>`
17- Optional: `--config <path>`
18
19## Workflow
20
211. Validate the project root and resolve the target `API.md`.
222. Load the canonical API-reference schema from `config/api-customization.template.yaml`, then merge any explicit override or project-local customization file.
233. In `check-only`, audit the required section schema, required subsection schema, required table of contents, placeholder content, and verification-command formatting.
244. In `apply`, keep edits bounded to the target `API.md` while creating a missing file from the bundled template and normalizing the document to the canonical structure.
255. Re-run the same audit to confirm post-fix status.
26
27## Canonical Base Contract
28
29The source of truth for the base API-reference contract lives in:
30
31- `config/api-customization.template.yaml`
32- `assets/API.template.md`
33
34The base contract requires:
35
36- a top-level title and short summary
37- a required `## Table of Contents`
38- canonical top-level sections for overview, API surface, authentication and access, requests and responses, errors, versioning and compatibility, local development and verification, and support ownership
39- required subsection structure for the sections that need stable consumer-facing detail
40
41## Writing Expectations
42
43- `Overview > Who This API Is For` should name the real consumers: humans, services, tools, packages, apps, or maintainers.
44- `Overview > Stability Status` should say whether the API is stable, experimental, internal, deprecated, or otherwise constrained.
45- `API Surface` should list concrete entry points and the protocol, transport, runtime, package interface, or file format used to reach each one.
46- `Authentication and Access` should describe credentials and permissions without inventing secrets, scopes, roles, or access paths.
47- `Requests and Responses` should document grounded request inputs, response outputs, and data models.
48- `Errors` should make failures actionable by documenting the error shape and common failure modes with likely causes or next checks.
49- `Versioning and Compatibility` should make the supported compatibility window and breaking-change handling explicit.
50- `Local Development and Verification > Verification` should prefer fenced commands or reproducible call examples with language info strings.
51- `Support and Ownership` should name only grounded teams, maintainers, issue trackers, services, or escalation paths.
52
53## Codex Subagent Fit
54
55When the user explicitly asks for subagents or parallel agent work, use subagents only for read-heavy API evidence gathering before the main workflow edits or reports. Good jobs include inventorying endpoints or public symbols, checking examples against tests, reading schema definitions, or comparing compatibility claims against release notes.
56
57Keep `apply` edits in the main thread because this skill owns one target `API.md` file and must avoid invented endpoints, schemas, credentials, or support promises. Ask workers for concise evidence and file references instead of replacement API prose.
58
59## Output Contract
60
61- Return Markdown plus JSON with:
62 - `run_context`
63 - `schema_contract`
64 - `schema_violations`
65 - `command_integrity_issues`
66 - `content_quality_issues`
67 - `fixes_applied`
68 - `post_fix_status`
69 - `errors`
70- If there are no issues and no errors, output exactly `No findings.`
71
72## Guardrails
73
74- Never auto-commit, auto-push, or open a PR.
75- Never invent commands, endpoints, protocols, schemas, environment variables, credentials, permissions, version guarantees, support paths, or compatibility promises that are not grounded in the repo.
76- Never edit files other than the target `API.md`.
77- Keep `API.md` as the canonical API-reference filename for this skill.
78- Treat this skill as a hard-enforced base template. Downstream plugins may specialize the schema, but the base skill should not do repo-profile inference.
79
80## References
81
82- `agents/openai.yaml`
83- `references/section-schema.md`
84- `references/output-contract.md`
85- `references/fix-policies.md`
86- `references/style-rules.md`
87- `references/api-customization.md`
88- `references/api-config-schema.md`
89- `references/project-api-maintenance-automation-prompts.md`
aibot88