# Api Doc Writer

> Use when writing or revising product-facing API interface documentation, especially for backend REST APIs that need a concise Chinese contract document with business rules, common API conventions, per-endpoint request/response details, combined request examples, and error code explanations. Trigger when the user asks for 接口文档, API 文档, 接口说明, Feishu/Lark API docs, or to rewrite implementation-heavy…

- **Type:** Skill
- **Install:** `agentstack add skill-kilimiaosix-agent-skills-api-doc-writer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [KilimiaoSix](https://agentstack.voostack.com/s/kilimiaosix)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [KilimiaoSix](https://github.com/KilimiaoSix)
- **Source:** https://github.com/KilimiaoSix/agent-skills/tree/main/skills/api-doc-writer

## Install

```sh
agentstack add skill-kilimiaosix-agent-skills-api-doc-writer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# API Doc Writer

## Trigger Conditions

Use this skill when the task is to produce or revise an API interface document for product, frontend, QA, or integration readers.

Typical inputs:
- Existing backend code, controller/service implementation, OpenAPI notes, PRD, design notes, or a finished endpoint.
- A request to write a Feishu/Lark document, Markdown API document, or interface specification.
- Feedback that the current document contains too much backend implementation detail or that examples/fields need to be simplified.

Do not use this for implementation plans, backend design docs, code review reports, or internal debugging writeups.

## Required Document Structure

Always use this top-level order:

1. 功能说明
2. 接口通用说明
3. 单个接口说明
4. 错误码说明

For multiple endpoints, repeat endpoint subsections under "3. 单个接口说明"; do not create a separate top-level section per endpoint.

## Workflow

1. Collect the public contract.
   - Identify endpoint name, method, public path, base URL or environment URL, auth requirement, request headers, query/body parameters, response wrapper, data fields, and error codes.
   - If code is available, verify field names and response shape from DTO/controller/tests, not from guesses.
   - Separate public behavior from backend implementation details.

2. Write "1. 功能说明".
   - Start with a one-paragraph purpose statement.
   - Add "业务规则" as a table.
   - Include only rules that affect client behavior, display, validation, permission, limits, fallback, or user-visible semantics.

3. Write "2. 接口通用说明".
   - Include protocol, default base URL if known, request/response format, authentication method, response wrapper, unit conventions, pagination conventions, and common headers.
   - Keep environment-specific values clearly marked as examples or default test values.

4. Write "3. 单个接口说明".
   - For each endpoint include:
     - Basic info table: interface name, method, path, full example URL, login requirement.
     - Request parameters split by Header, Query, Path, and Body. Write "无" for absent parameter groups.
     - Response field table for `data` fields, with type and client-facing meaning.
     - A single "请求示例" subsection that combines curl command and scenario responses.

5. Write "4. 错误码说明".
   - Provide a table with code, meaning, trigger scenario, and client handling suggestion.
   - Include auth errors, validation errors, permission errors, and service errors only when they can occur for this API.
   - If the API falls back and still returns success, describe that behavior in business rules instead of inventing an error code.

6. Final pass.
   - Remove implementation file paths, class names, service names, Feign/client names, database table plans, test commands, build output, and backend verification notes unless the user explicitly asks for an engineering appendix.
   - Verify examples contain only fields that the API actually returns.
   - Check that no internal-only field, duplicated semantic field, placeholder token, private URL, account, or credential appears in the final document.

## Hard Rules

- The document is an API contract, not an implementation report.
- Do not include backend file paths, modified file lists, compile commands, unit test commands, deployment notes, or internal call chains in the default output.
- Do not expose internal-only fields. If a field only explains how the server made a decision and the client does not need it, omit it.
- Do not duplicate field semantics. If `limitBytes` already communicates the effective quota, do not also expose fields like `member`, `limitType`, or `action` unless the real API returns them and the client has a use for them.
- Do not say "temporarily fixed", "not fully launched", or "not yet counted" when the client contract is a display rule. Prefer client-facing wording such as "when this field is `-1`, the client should not display the detailed value".
- Do not split examples into separate "成功用例", "失败用例", and "Curl 请求命令" sections. Merge them under one "请求示例" subsection.
- Do not invent request/response fields, status codes, or error codes. Mark unknowns as "待确认" only if they cannot be discovered.
- Do not include real access tokens, cookies, private account IDs, customer data, or private URLs. Use placeholders such as `{access_token}`, `{domain}`, and `{id}`.

## Output Contract

When returning the document in chat or Markdown, output exactly these sections:

```markdown
# 

## 1. 功能说明

### 1.1 业务规则

## 2. 接口通用说明

### 2.1 通用响应结构

## 3. 单个接口说明

### 3.1 

#### 3.1.1 基本信息

#### 3.1.2 请求参数

#### 3.1.3 响应字段

#### 3.1.4 请求示例

## 4. 错误码说明
```

The "请求示例" subsection must include:
- one curl command;
- at least one success response;
- relevant failure responses such as unauthenticated, missing/invalid parameter, permission denied, or service exception when applicable.

## Feishu/Lark Notes

When publishing to Feishu/Lark:
- Preserve the same four-section structure.
- Use tables for rules, parameters, response fields, and error codes.
- Use code blocks for curl and JSON examples.
- After update, fetch or search the remote document to confirm obsolete headings and removed fields are not still present.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [KilimiaoSix](https://github.com/KilimiaoSix)
- **Source:** [KilimiaoSix/agent-skills](https://github.com/KilimiaoSix/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-kilimiaosix-agent-skills-api-doc-writer
- Seller: https://agentstack.voostack.com/s/kilimiaosix
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.