# Smolify API Docs

> Analyze an API repository with Codex, create or update safe Markdown documentation, validate a Smolify bundle, and publish it only after the user reviews the generated diff. Use when the user asks to document, refresh, audit, or publish an API with Smolify.

- Skill: `justrach/smolify-api-docs` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add justrach/smolify-api-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/justrach/smolify-api-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: justrach (https://skillmd.com/u/justrach)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/justrach/smolify-api-docs

---


# Smolify API Docs

Turn an API implementation into accurate, reviewable documentation. The source
of truth is the repository, not model memory. Write Markdown only; never emit
runtime MDX, JSX, scripts, or unsanitized HTML.

## Preconditions

1. Confirm the current task uses GPT-5.6. If it does not, stop and ask the user
   to switch models before generation.
2. Read the repository's `AGENTS.md` and follow the closest applicable guidance.
3. Locate API evidence in this order:
   - OpenAPI/Swagger, GraphQL, protobuf, or RPC contracts
   - route/controller definitions
   - request and response schemas
   - authentication and authorization middleware
   - tests and fixtures
   - existing documentation and examples
4. Do not make network calls to the production API unless the user explicitly
   authorizes them and provides a safe test target.

## Workflow

### 1. Inventory

Create a compact route inventory containing method, path, authentication,
request schema, success response, error responses, and supporting source files.
Flag conflicts between contracts, code, and tests instead of guessing.

### 2. Plan

Propose a navigation tree. Prefer task-oriented guides plus a reference page per
endpoint group. Ask for clarification only when a product decision materially
changes the output; otherwise record the uncertainty in the generated page.

### 3. Generate

Write `.smolify/smolify.bundle.json` matching `references/bundle.schema.json`.

- Every page must contain useful prose, not placeholder sections.
- Include runnable examples only when values are supported by code or fixtures.
- Record supporting paths in `sourceFiles`.
- Never include secrets copied from environment files, fixtures, logs, or code.
- Use `generator.name = "codex"` and the exact active model identifier.
- Use ISO 8601 UTC for `generatedAt`.

### 4. Validate

Run:

```bash
node <skill-directory>/scripts/validate.mjs .smolify/smolify.bundle.json
```

Fix every validation failure. Then review the generated git diff for leaked
secrets, invented behavior, broken examples, duplicated slugs, and navigation
entries without pages.

### 5. Publish

Publishing changes external state. Do it only when the user explicitly asks to
publish after reviewing the diff.

Prefer the authenticated Smolify MCP tool `publish_docs` when it is available.
The MCP client completes OAuth authorization-code + PKCE in the browser; never
ask the user to paste its access or refresh token into chat. Pass the validated
bundle and project slug to the tool, then report its deployment ID and URL.

For headless CI or installations without the MCP, use the project-token
fallback below.

Require these environment variables:

- `SMOLIFY_PUBLISH_TOKEN` — project-scoped token from the Smolify dashboard
- `SMOLIFY_ENDPOINT` — optional; defaults to `https://app.smol.ly`
- `SMOLIFY_PROJECT` — the project slug

Then run:

```bash
node <skill-directory>/scripts/publish.mjs .smolify/smolify.bundle.json
```

Never print the publish token. Report the deployment ID and public URL returned
by the service.

## Updating existing docs

When `.smolify/smolify.bundle.json` already exists, preserve unaffected prose
and navigation. Use the git diff to determine which API surfaces changed, then
update only impacted pages unless a broader rewrite is necessary for accuracy.

## Reviewing public Smolify projects

When the user asks to review or improve public Smolify documentation:

1. Call `discover_public_projects` and choose the exact project.
2. If authenticated, call `whoami` once so the user can see whether the review
   will advance community status. Treat `officialPublisherName` returned by
   discovery as source provenance only, never as a security claim.
3. Call `search_docs` before `get_doc_page`; read bounded slices and inspect the
   public source repository when its URL is available.
4. Call `rate_docs` with the exact active GPT-5.6 model identifier and concise,
   evidence-grounded notes.
5. Propose an improvement only when you can produce a complete valid bundle.
   Preserve accurate unaffected content, cite supporting paths in `sourceFiles`,
   and call `propose_doc_improvement` with a clear summary and rationale.
6. Tell the user that the proposal is pending. Never describe a proposal as
   published; only the project owner can preview, accept, and activate it.