GET /api/users/:id

GET /api/users/:id

Retrieves a user by their unique identifier.

Parameters

Name	Type	Required	Description
id	string	Yes	The user's unique identifier

Response

{
  "id": "abc123",
  "name": "John Doe",
  "email": "[e-mail]"
}

Errors

Code	Description
404	User not found
401	Unauthorized

Example

curl -X GET https://api.example.com/api/users/abc123 \
  -H "Authorization: Bearer <token>"

这个示例浓缩了全部要点：**描述一句话讲清用途；参数表格精确到类型与必填性；响应给出真实 JSON 样例；错误码单独成表；示例可复制可运行**。子代理在撰写任何 API 文档时都会以此为格式基准。

## 从源码与仓库生态看设计意图

### 工具集为什么是 Read / Write / Grep

对照 [04-subagents/README.md](https://gitcode.com/GitHub_Trending/cl/claude-howto/blob/da6e09e7987d1edccedd2f9a52ee2fc6cfd4257e/04-subagents/README.md?utm_source=gitcode_repo_files) 中的配置字段说明可以推断：`tools` 字段省略时子代理继承全部工具，而此处**显式列出三个工具**属于"从最小权限出发"的策略。文档写作的核心动作是"读懂代码（Read/Grep）→ 写文件（Write）"，并不需要执行命令或编辑代码。这样的约束既降低了误操作风险，也让模型把全部注意力集中在文档质量本身。

### 与文档插件的协作

仓库的 [07-plugins/documentation/README.md](https://gitcode.com/GitHub_Trending/cl/claude-howto/blob/da6e09e7987d1edccedd2f9a52ee2fc6cfd4257e/07-plugins/documentation/README.md?utm_source=gitcode_repo_files) 展示了一条更完整的链路：插件内提供了 `api-documenter`、`code-commentator`、`example-generator` 三个更细分的文档子代理，以及 `/generate-api-docs`、`/generate-readme`、`/sync-docs`、`/validate-docs` 四个斜杠命令。其中 `api-documenter` 的职责描述（端点文档、参数描述、响应模式、curl/JS/Python 示例、错误码）与 `documentation-writer` 高度互补——前者是插件内置的专职子代理，后者是通用型文档写手，二者共用同一套模板规范。插件的工作流示例也印证了子代理的运作方式：扫描 `src/api/` 端点 → 委派给 api-documenter → 提取函数签名与 JSDoc → 按模块/端点组织 → 套用模板 → 生成含多语言示例的 Markdown 文档。

### 与 Skills 的边界

[03-skills/README.md](https://gitcode.com/GitHub_Trending/cl/claude-howto/blob/da6e09e7987d1edccedd2f9a52ee2fc6cfd4257e/03-skills/README.md?utm_source=gitcode_repo_files) 中有一张"Skills vs Other Features"对照表：**Skills** 用于可复用的专业知识自动加载，**Subagents** 用于隔离上下文的任务委派。若文档规范需要沉淀为团队知识（例如"所有文档必须遵循 api-endpoint 模板"），可以封装为 Skill；而"针对某个模块实际写一份文档"则更适合交给 `documentation-writer` 这类子代理执行。二者可组合使用：Skill 提供规范，子代理负责执行。

## 安装与落地到你的项目

`documentation-writer.md` 本身是仓库中的示例文件，你可以将其安装到自己的项目：

**方式一：让 Claude 直接创建**（推荐）
```text
Create a project-level subagent that writes technical documentation.
Give it access to Read, Write, and Grep.

方式二：复制到项目级目录

cd /path/to/your/project
mkdir -p .claude/agents
cp /path/to/claude-howto/04-subagents/documentation-writer.md .claude/agents/

方式三：复制到用户级目录（对所有项目生效）

mkdir -p ~/.claude/agents
cp /path/to/claude-howto/04-subagents/documentation-writer.md ~/.claude/agents/