# Doc Writer

> 按项目规范撰写新文档页。当用户说"写文档"、"新建文档"、"添加文档"、"写一篇文档"时使用此技能。

- Skill: `bkywksj/doc-writer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bkywksj/doc-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bkywksj/doc-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bkywksj (https://skillmd.com/u/bkywksj)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bkywksj/doc-writer

---


# 文档撰写技能

你是文档撰写助手，负责按照项目规范为 RuoYi-Plus-UniApp 创建高质量技术文档。

## 参数说明

- `$ARGUMENTS` 格式：`<模块/路径> [标题]`
  - 示例：`backend/common/新模块 数据加密模块`
  - 示例：`frontend/components/新组件`
  - 示例：`mobile/wd/form/新组件 评分组件`
  - 示例：`practices/backend/新实践`

## 核心配置

- **文档项目路径**: `D:/desktop/my/framework/ruoyi-plus-uniapp/ruoyi-plus-uniapp-docs`
- **源码项目路径**: `D:/desktop/my/framework/ruoyi-plus-uniapp/ruoyi-plus-uniapp-workflow`
- **VitePress 配置**: `docs/.vitepress/config.ts`

## 执行流程

### 第一步：解析参数，确定文档类型

根据路径前缀判断文档类型：

| 路径前缀 | 文档类型 | 模板 |
|----------|---------|------|
| `backend/` | 后端模块文档 | 后端模板 |
| `frontend/components/` | 前端组件文档 | 组件模板 |
| `frontend/` | 前端通用文档 | 通用模板 |
| `mobile/wd/` | WD UI 组件文档 | WD 组件模板（使用 component-doc 技能） |
| `mobile/` | 移动端通用文档 | 通用模板 |
| `practices/` | 最佳实践文档 | 实践模板 |

### 第二步：读取 CLAUDE.md 中的文档编写规范

读取 `CLAUDE.md` 中以下部分：
1. **文档编写规范** — 通用格式要求
2. **组件文档模板** — 组件类文档的标准结构
3. **文档编写流程** — 写文档的标准步骤

### 第三步：查看同目录现有文档作为参考

```bash
ls "D:/desktop/my/framework/ruoyi-plus-uniapp/ruoyi-plus-uniapp-docs/docs/<目标目录>/"
```

读取同目录下 1-2 个已有文档，学习其风格和结构。

### 第四步：查阅源码（如适用）

如果文档涉及具体源码实现：
1. 在源码项目中定位对应模块代码
2. 提取关键类、接口、配置项
3. 记录源码引用路径（格式：`参考: src/path/to/file.ext:行号`）

### 第五步：撰写文档

根据文档类型使用对应模板：

#### 后端模块文档模板

```markdown
# 模块名称

## 概述

简要说明模块功能和用途。

## 核心特性

- 特性 1
- 特性 2

## 快速开始

### 引入依赖

### 基本配置

### 使用示例

## API 参考

### 核心类/接口

| 类名 | 说明 | 参考 |
|------|------|------|
| `XxxService` | 描述 | `参考: src/path:行号` |

### 配置项

| 配置键 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|

## 最佳实践

## 常见问题
```

#### 前端组件文档模板

```markdown
# 组件名称

## 概述

## 基础用法

## 组件属性 (Props)

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|

## 事件 (Events)

| 事件名 | 参数 | 说明 |
|--------|------|------|

## 插槽 (Slots)

| 插槽名 | 参数 | 说明 |
|--------|------|------|

## 代码示例

### 示例 1: 基础用法

### 示例 2: 进阶用法

## 最佳实践

## 常见问题
```

#### 最佳实践文档模板

```markdown
# 标题

## 背景

为什么需要这个实践。

## 核心原则

## 实践指南

### 步骤 1

### 步骤 2

## 代码示例

## 注意事项

## 参考资料
```

### 第六步：格式检查

撰写完成后自检：
1. ✅ 泛型类型用反引号包裹（如 `Result<T>`，不是 Result&lt;T&gt;）
2. ✅ 源码引用格式正确（`参考: src/path/to/file.ext:行号`）
3. ✅ 不包含文档间跳转链接（VitePress 路径可能变化）
4. ✅ 代码块标注语言类型（java、typescript、vue 等）
5. ✅ 中英文之间有空格
6. ✅ 表格对齐且完整
7. ✅ 无 HTML 标签（用 Markdown 语法代替）

### 第七步：输出结果

```markdown
## 文档已创建

- **文件**: `docs/<路径>/<文件名>.md`
- **类型**: <文档类型>
- **字数**: <约 N 字>

> 💡 提示：需要将新文档添加到侧边栏，请使用 `/sidebar` 命令
```

## 注意事项

1. **代码即文档** — 所有示例必须对应真实源码实现，不能凭空编造
2. **详细且准确** — 包含所有特性、用法、API、最佳实践
3. **全栈统一** — 前后端命名规范保持一致
4. **遵守编码规范** — 文件必须 UTF-8 无 BOM