Scribe Role Skill

Scribe角色技能

Description

描述

Create and maintain comprehensive, accurate, and user-friendly documentation for codebases, APIs, deployment processes, and end-user guides. This skill implements professional technical writing practices including documentation planning, structured content creation, and maintenance workflows.

为代码库、API、部署流程及终端用户指南创建并维护全面、准确且易用的文档。该技能采用专业技术写作规范，包括文档规划、结构化内容创建及维护工作流。

When to Use This Skill

何时使用此技能

Creating project documentation (README, guides, etc.)
Documenting APIs and endpoints
Writing deployment and build instructions
Creating user manuals and usage guides
Documenting system architecture (with architect)
Developing onboarding materials for new developers
Maintaining and updating existing documentation

创建项目文档（README、指南等）
编写API及端点文档
撰写部署与构建说明
创建用户手册与使用指南
记录系统架构（与架构师协作）
为新开发人员制作入职材料
维护与更新现有文档

When NOT to Use This Skill

何时不使用此技能

For system architecture design (use architect-role-skill)
For code implementation (use builder-role-skill)
For infrastructure deployment (use devops-role-skill)
For testing procedures (use validator-role-skill)

系统架构设计（使用architect-role-skill）
代码实现（使用builder-role-skill）
基础设施部署（使用devops-role-skill）
测试流程（使用validator-role-skill）

Prerequisites

前提条件

Access to project source code for analysis
Understanding of target audience (developers vs end-users)
Existing documentation to review (if updating)
Access to architectural and planning documents

可访问项目源代码进行分析
了解目标受众（开发人员vs终端用户）
可查阅现有文档（如需更新）
可访问架构与规划文档

Workflow

工作流

Phase 1: Comprehensive Project Documentation

第一阶段：全面项目文档

Create complete documentation suite for a project.

Step 1.1: Codebase Analysis

bash

undefined

为项目创建完整的文档套件。

步骤1.1：代码库分析

bash

undefined

Understand project structure

tree -L 3 -I 'node_modules|.git|dist|build'

Identify main entry points

find . -name "index." -o -name "main." -o -name "app.*" | grep -v node_modules

Review package manifest

cat package.json || cat requirements.txt || cat pom.xml || cat Cargo.toml

Check existing documentation

find . -name ".md" -o -name ".rst" | grep -v node_modules


**Step 1.2: Documentation Planning**

Create `DOCUMENTATION_PLAN.md`:

```markdown

find . -name ".md" -o -name ".rst" | grep -v node_modules


**步骤1.2：文档规划**

创建`DOCUMENTATION_PLAN.md`文件：

```markdown

Documentation Plan: [Project Name]

Current State Assessment

当前状态评估

Existing docs: [List what exists]
Documentation gaps: [What's missing]
Outdated sections: [What needs updating]

现有文档：[列出已有内容]
文档缺口：[缺失内容]
过时章节：[需要更新的内容]

Documentation Structure

文档结构

docs/
├── README.md                    # Project overview
├── GETTING_STARTED.md          # Quick start guide
├── BUILDING.md                 # Build instructions
├── DEPLOYMENT.md               # Deployment guide
├── USAGE.md                    # User manual
├── API.md                      # API reference
├── ARCHITECTURE.md             # System architecture
├── CONTRIBUTING.md             # Contribution guidelines
├── TROUBLESHOOTING.md          # Common issues
└── CHANGELOG.md                # Version history

docs/
├── README.md                    # 项目概述
├── GETTING_STARTED.md          # 快速入门指南
├── BUILDING.md                 # 构建说明
├── DEPLOYMENT.md               # 部署指南
├── USAGE.md                    # 用户手册
├── API.md                      # API参考文档
├── ARCHITECTURE.md             # 系统架构
├── CONTRIBUTING.md             # 贡献指南
├── TROUBLESHOOTING.md          # 常见问题
└── CHANGELOG.md                # 版本历史

Priority

优先级

Critical (Must Have):
- README.md
- BUILDING.md
- DEPLOYMENT.md
Important (Should Have):
- API.md
- USAGE.md
- TROUBLESHOOTING.md
Nice to Have:
- ARCHITECTURE.md (if not done by architect)
- CONTRIBUTING.md
- Advanced guides

关键（必备）:
- README.md
- BUILDING.md
- DEPLOYMENT.md
重要（应备）:
- API.md
- USAGE.md
- TROUBLESHOOTING.md
可选:
- ARCHITECTURE.md（若架构师未完成）
- CONTRIBUTING.md
- 进阶指南

Timeline

时间线

Phase 1 (Critical): Immediate
Phase 2 (Important): Next sprint
Phase 3 (Nice to Have): Following sprint


**Step 1.3: Create Core Documentation**

第一阶段（关键）：立即完成
第二阶段（重要）：下一个迭代
第三阶段（可选）：后续迭代


**步骤1.3：创建核心文档**

README.md Template

README.md模板

markdown

undefined

markdown

undefined

[Project Name]

[One-sentence description of what this project does]

[一句话描述项目功能]

Overview

概述

[2-3 paragraph description covering:

What problem does this solve?
Who is it for?
What are the key features?]

[2-3段描述，涵盖：

解决的问题
目标用户
核心功能]

Quick Start

快速入门

bash

undefined

bash

undefined

Clone the repository

git clone [repository-url] cd [project-name]

Install dependencies

npm install # or pip install -r requirements.txt, etc.

Run the application

npm start # or python main.py, etc.

undefined

npm start # or python main.py, etc.

undefined

Features

功能特性

Feature 1: Description
Feature 2: Description
Feature 3: Description

Feature 1: Description
Feature 2: Description
Feature 3: Description

Documentation

文档

Getting Started Guide
Building Instructions
Deployment Guide
API Documentation
User Manual

快速入门指南
构建说明
部署指南
API文档
用户手册

Requirements

环境要求

[Runtime/Language]: version X.X+
[Database]: version Y.Y+ (if applicable)
[Other dependencies]

[运行时/语言]: version X.X+
[数据库]: version Y.Y+（如适用）
[其他依赖]

Installation

安装

See GETTING_STARTED.md for detailed installation instructions.

详细安装说明请查看GETTING_STARTED.md。

Usage

使用

See USAGE.md for comprehensive usage documentation.

完整使用文档请查看USAGE.md。

Contributing

贡献

See CONTRIBUTING.md for contribution guidelines.

贡献指南请查看CONTRIBUTING.md。

License

许可证

[License type and link]

[许可证类型及链接]

Support

支持

Issues: [GitHub issues link]
Documentation: [Documentation link]
Community: [Discord/Slack/Forum link]

问题反馈：[GitHub issues链接]
文档：[文档链接]
社区：[Discord/Slack/论坛链接]

Credits

致谢

[Acknowledgments, authors, contributors]

undefined

[鸣谢、作者、贡献者]

undefined

BUILDING.md Template

BUILDING.md模板

markdown

undefined

markdown

undefined

Building [Project Name]

This guide covers how to build the application from source.

Prerequisites

Required Tools

[Tool 1]: version X.X+ ([installation link])
[Tool 2]: version Y.Y+ ([installation link])
[Tool 3]: version Z.Z+ ([installation link])

[Tool 1]: version X.X+ ([installation link])
[Tool 2]: version Y.Y+ ([installation link])
[Tool 3]: version Z.Z+ ([installation link])

Optional Tools

[Tool]: For [purpose]

[Tool]: For [purpose]

Environment Setup

macOS

bash

undefined

bash

undefined

Install dependencies

brew install [package1] [package2]

Set environment variables

export VAR_NAME=value

undefined

export VAR_NAME=value

undefined

Linux (Ubuntu/Debian)

bash

undefined

bash

undefined

Install dependencies

sudo apt-get update sudo apt-get install [package1] [package2]

Set environment variables

export VAR_NAME=value

undefined

export VAR_NAME=value

undefined

Windows

powershell

undefined

powershell

undefined

Install dependencies using chocolatey

choco install [package1] [package2]

Set environment variables

$env:VAR_NAME="value"

undefined

$env:VAR_NAME="value"

undefined

Building the Application

Development Build

bash

undefined

bash

undefined

Install dependencies

npm install # or equivalent

Build for development

npm run build:dev

Output location: ./dist/

undefined

undefined

Production Build

bash

undefined

bash

undefined

Clean previous builds

npm run clean

Install production dependencies

npm ci --production

Build optimized version

npm run build:prod

Output location: ./dist/production/

undefined

undefined

Build Configuration

Configuration files:

```
build.config.js
```
: Main build configuration
```
.env.build
```
: Build-time environment variables
```
webpack.config.js
```
: Bundler configuration (if applicable)

Key configuration options:

javascript

{
  mode: 'production',        // production | development
  optimization: true,        // Enable optimizations
  minify: true,             // Minify output
  sourceMaps: false         // Generate source maps
}

Configuration files:

```
build.config.js
```
: Main build configuration
```
.env.build
```
: Build-time environment variables
```
webpack.config.js
```
: Bundler configuration (if applicable)

Key configuration options:

javascript

{
  mode: 'production',        // production | development
  optimization: true,        // Enable optimizations
  minify: true,             // Minify output
  sourceMaps: false         // Generate source maps
}

Build Artifacts

After successful build, the following artifacts are generated:

dist/
├── app.[hash].js          # Main application bundle
├── vendor.[hash].js       # Third-party dependencies
├── styles.[hash].css      # Compiled styles
├── assets/               # Static assets
│   ├── images/
│   └── fonts/
└── index.html           # Entry point

After successful build, the following artifacts are generated:

dist/
├── app.[hash].js          # Main application bundle
├── vendor.[hash].js       # Third-party dependencies
├── styles.[hash].css      # Compiled styles
├── assets/               # Static assets
│   ├── images/
│   └── fonts/
└── index.html           # Entry point

Build Troubleshooting

Common Issues

Issue: Build fails with "out of memory" error

bash

undefined

Issue: Build fails with "out of memory" error

bash

undefined

Solution: Increase Node memory limit

export NODE_OPTIONS="--max-old-space-size=4096" npm run build


**Issue**: Dependency resolution fails
```bash

export NODE_OPTIONS="--max-old-space-size=4096" npm run build


**Issue**: Dependency resolution fails
```bash

Solution: Clear cache and reinstall

rm -rf node_modules package-lock.json npm cache clean --force npm install


**Issue**: Module not found errors
```bash

rm -rf node_modules package-lock.json npm cache clean --force npm install


**Issue**: Module not found errors
```bash

Solution: Verify all dependencies installed

npm list --depth=0 npm install [missing-package]

undefined

npm list --depth=0 npm install [missing-package]

undefined

Continuous Integration Builds

This project uses [CI system] for automated builds.

Build triggers:

Push to
```
main
```
branch: Production build
Push to
```
develop
```
branch: Development build
Pull requests: Test build

Build status:

This project uses [CI system] for automated builds.

Build triggers:

Push to
```
main
```
branch: Production build
Push to
```
develop
```
branch: Development build
Pull requests: Test build

Build status:

Build Performance

Typical build times:

Development: ~30 seconds
Production: ~2 minutes

To improve build performance:

Use incremental builds:
```
npm run build:watch
```
Enable caching: Configure in
```
build.config.js
```
Parallelize builds: Use
```
--parallel
```
flag

Typical build times:

Development: ~30 seconds
Production: ~2 minutes

To improve build performance:

Use incremental builds:
```
npm run build:watch
```
Enable caching: Configure in
```
build.config.js
```
Parallelize builds: Use
```
--parallel
```
flag

Next Steps

After building, see:

DEPLOYMENT.md for deployment instructions
TESTING.md for running tests

undefined

After building, see:

DEPLOYMENT.md for deployment instructions
TESTING.md for running tests

undefined

DEPLOYMENT.md Template

DEPLOYMENT.md模板

markdown

undefined

markdown

undefined

Deploying [Project Name]

This guide covers deploying the application to various environments.

Environments

Environment	Purpose	URL	Access
Development	Local development	localhost:3000	All developers
QA	Testing	qa.example.com	QA team
Staging	Pre-production validation	staging.example.com	Internal users
Production	Live application	www.example.com	Public

Environment	Purpose	URL	Access
Development	Local development	localhost:3000	All developers
QA	Testing	qa.example.com	QA team
Staging	Pre-production validation	staging.example.com	Internal users
Production	Live application	www.example.com	Public

Prerequisites

Required

Built application artifacts (see BUILDING.md)
Access credentials for target environment
[Cloud provider] CLI tools installed and configured

Built application artifacts (see BUILDING.md)
Access credentials for target environment
[Cloud provider] CLI tools installed and configured

Environment Variables

Create

.env.[environment]

file:

bash

undefined

Create

.env.[environment]

file:

bash

undefined

Application

NODE_ENV=production PORT=3000 LOG_LEVEL=info

Database

DATABASE_URL=postgresql://user:pass@host:5432/dbname DATABASE_POOL_SIZE=10

API Keys (use secrets manager in production)

API_KEY=your-api-key SECRET_KEY=your-secret-key

Feature Flags

FEATURE_X_ENABLED=true

undefined

FEATURE_X_ENABLED=true

undefined

Deployment Methods

Method 1: Manual Deployment

Step 1: Prepare Application

bash

undefined

Step 1: Prepare Application

bash

undefined

Build production artifacts

npm run build:prod

Verify build

ls -la dist/


**Step 2: Deploy to Server**
```bash

ls -la dist/


**Step 2: Deploy to Server**
```bash

Copy files to server

scp -r dist/* user@server:/var/www/app/

SSH into server

ssh user@server

Restart application

sudo systemctl restart app-service


**Step 3: Verify Deployment**
```bash

sudo systemctl restart app-service


**Step 3: Verify Deployment**
```bash

Check service status

sudo systemctl status app-service

Check logs

sudo tail -f /var/log/app/application.log

Test endpoint

curl https://your-domain.com/health

undefined

curl https://your-domain.com/health

undefined

Method 2: Docker Deployment

Step 1: Build Docker Image

bash

undefined

Step 1: Build Docker Image

bash

undefined

Build image

docker build -t app-name:version .

Tag for registry

docker tag app-name:version registry.example.com/app-name:version

Push to registry

docker push registry.example.com/app-name:version


**Step 2: Deploy Container**
```bash

docker push registry.example.com/app-name:version


**Step 2: Deploy Container**
```bash

Pull latest image

docker pull registry.example.com/app-name:version

Stop existing container

docker stop app-container || true docker rm app-container || true

Run new container

docker run -d
--name app-container
--env-file .env.production
-p 80:3000
--restart unless-stopped
registry.example.com/app-name:version

Verify

docker logs app-container

undefined

docker logs app-container

undefined

Method 3: Kubernetes Deployment

Step 1: Prepare Kubernetes Manifests

yaml

undefined

Step 1: Prepare Kubernetes Manifests

yaml

undefined

deployment.yaml

apiVersion: apps/v1 kind: Deployment metadata: name: app-deployment spec: replicas: 3 selector: matchLabels: app: myapp template: metadata: labels: app: myapp spec: containers: - name: app image: registry.example.com/app-name:version ports: - containerPort: 3000 envFrom: - configMapRef: name: app-config - secretRef: name: app-secrets


**Step 2: Deploy to Cluster**
```bash

apiVersion: apps/v1 kind: Deployment metadata: name: app-deployment spec: replicas: 3 selector: matchLabels: app: myapp template: metadata: labels: app: myapp spec: containers: - name: app image: registry.example.com/app-name:version ports: - containerPort: 3000 envFrom: - configMapRef: name: app-config - secretRef: name: app-secrets


**Step 2: Deploy to Cluster**
```bash

Apply configurations

kubectl apply -f k8s/

Check deployment status

kubectl rollout status deployment/app-deployment

Verify pods running

kubectl get pods -l app=myapp

Check logs

kubectl logs -l app=myapp --tail=100

undefined

kubectl logs -l app=myapp --tail=100

undefined

Method 4: Cloud Platform (AWS/GCP/Azure)

AWS Elastic Beanstalk

bash

undefined

bash

undefined

Initialize EB

eb init -p node.js-16 app-name --region us-west-2

Create environment

eb create production --instance-type t3.medium

Deploy

eb deploy

Check status

eb status

undefined

eb status

undefined

Google Cloud Platform

bash

undefined

bash

undefined

Deploy to App Engine

gcloud app deploy app.yaml --project=project-id

View logs

gcloud app logs tail -s default

Open in browser

gcloud app browse

undefined

gcloud app browse

undefined

Azure App Service

bash

undefined

bash

undefined

Create resource group

az group create --name myResourceGroup --location eastus

Create app service plan

az appservice plan create --name myAppServicePlan
--resource-group myResourceGroup --sku B1 --is-linux

Create web app

az webapp create --resource-group myResourceGroup
--plan myAppServicePlan --name myUniqueAppName
--runtime "NODE|16-lts"

Deploy

az webapp deployment source config-zip
--resource-group myResourceGroup
--name myUniqueAppName
--src dist.zip

undefined

az webapp deployment source config-zip
--resource-group myResourceGroup
--name myUniqueAppName
--src dist.zip

undefined

Post-Deployment Verification

Health Checks

bash

undefined

bash

undefined

Application health

curl https://your-domain.com/health

Expected response:

{ "status": "healthy", "version": "1.2.3", "uptime": 12345 }

Database connectivity

curl https://your-domain.com/health/db

Dependencies status

curl https://your-domain.com/health/dependencies

undefined

curl https://your-domain.com/health/dependencies

undefined

Smoke Tests

bash

undefined

bash

undefined

Test critical endpoints

curl -X POST https://your-domain.com/api/test
-H "Content-Type: application/json"
-d '{"test": "data"}'

Test authentication

curl https://your-domain.com/api/protected
-H "Authorization: Bearer $TOKEN"

undefined

curl https://your-domain.com/api/protected
-H "Authorization: Bearer $TOKEN"

undefined

Monitoring Setup

Set up application monitoring (see DevOps docs)
Configure alerts for errors and performance
Verify logs are being collected
Check metrics dashboard

Set up application monitoring (see DevOps docs)
Configure alerts for errors and performance
Verify logs are being collected
Check metrics dashboard

Rollback Procedures

Docker Rollback

bash

undefined

bash

undefined

Identify previous version

docker images registry.example.com/app-name

Deploy previous version

docker stop app-container docker rm app-container docker run -d --name app-container
registry.example.com/app-name:previous-version

undefined

docker stop app-container docker rm app-container docker run -d --name app-container
registry.example.com/app-name:previous-version

undefined

Kubernetes Rollback

bash

undefined

bash

undefined

View rollout history

kubectl rollout history deployment/app-deployment

Rollback to previous version

kubectl rollout undo deployment/app-deployment

Rollback to specific revision

kubectl rollout undo deployment/app-deployment --to-revision=2

undefined

kubectl rollout undo deployment/app-deployment --to-revision=2

undefined

Troubleshooting

Deployment Fails

Check: Build artifacts

bash

ls -la dist/

Check: Build artifacts

bash

ls -la dist/

Verify all necessary files present


**Check**: Environment variables
```bash
printenv | grep APP_


**Check**: Environment variables
```bash
printenv | grep APP_

Verify all required variables set


**Check**: Server logs
```bash
tail -f /var/log/app/error.log


**Check**: Server logs
```bash
tail -f /var/log/app/error.log

Application Not Responding

Check: Service status

bash

sudo systemctl status app-service

Check: Port bindings

bash

sudo netstat -tulpn | grep :3000

Check: Firewall rules

bash

sudo iptables -L -n | grep 3000

Check: Service status

bash

sudo systemctl status app-service

Check: Port bindings

bash

sudo netstat -tulpn | grep :3000

Check: Firewall rules

bash

sudo iptables -L -n | grep 3000

Security Considerations

Never commit secrets to version control
Use environment variables or secrets manager
Enable HTTPS/TLS for all environments
Implement proper authentication and authorization
Keep dependencies updated
Regular security audits

Never commit secrets to version control
Use environment variables or secrets manager
Enable HTTPS/TLS for all environments
Implement proper authentication and authorization
Keep dependencies updated
Regular security audits

Next Steps

After deployment:

Review MONITORING.md for observability setup
Configure BACKUP.md procedures
Set up ALERTS.md for critical issues

---

After deployment:

Review MONITORING.md for observability setup
Configure BACKUP.md procedures
Set up ALERTS.md for critical issues

---

Phase 2: API Documentation

第二阶段：API文档

Create comprehensive API reference documentation.

Step 2.1: Create API.md

markdown

undefined

创建全面的API参考文档。

步骤2.1：创建API.md

markdown

undefined

API Documentation

Base URL

Production: https://api.example.com/v1
Staging: https://staging-api.example.com/v1
Development: http://localhost:3000/v1

Production: https://api.example.com/v1
Staging: https://staging-api.example.com/v1
Development: http://localhost:3000/v1

Authentication

All API requests require authentication using Bearer tokens:

bash

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.example.com/v1/endpoint

All API requests require authentication using Bearer tokens:

bash

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.example.com/v1/endpoint

Obtaining a Token

bash

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password"
}

Response:
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

bash

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password"
}

Response:
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

Endpoints

Users

Get User

GET /users/:id

Parameters:

```
id
```
(path, required): User ID

Response:

json

{
  "id": "123",
  "email": "user@example.com",
  "name": "John Doe",
  "created_at": "2025-01-01T00:00:00Z"
}

Example:

bash

curl -H "Authorization: Bearer TOKEN" \
  https://api.example.com/v1/users/123

GET /users/:id

Parameters:

```
id
```
(path, required): User ID

Response:

json

{
  "id": "123",
  "email": "user@example.com",
  "name": "John Doe",
  "created_at": "2025-01-01T00:00:00Z"
}

Example:

bash

curl -H "Authorization: Bearer TOKEN" \
  https://api.example.com/v1/users/123

Create User

POST /users

Request Body:

json

{
  "email": "user@example.com",
  "password": "SecurePass123!",
  "name": "John Doe"
}

Response:

201 Created

json

{
  "id": "124",
  "email": "user@example.com",
  "name": "John Doe",
  "created_at": "2025-11-10T00:00:00Z"
}

Errors:

```
400 Bad Request
```
: Invalid input
```
409 Conflict
```
: Email already exists

POST /users

Request Body:

json

{
  "email": "user@example.com",
  "password": "SecurePass123!",
  "name": "John Doe"
}

Response:

201 Created

json

{
  "id": "124",
  "email": "user@example.com",
  "name": "John Doe",
  "created_at": "2025-11-10T00:00:00Z"
}

Errors:

```
400 Bad Request
```
: Invalid input
```
409 Conflict
```
: Email already exists

Error Handling

All errors follow this format:

json

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": ["Specific error detail"]
  }
}

Common error codes:

```
UNAUTHORIZED
```
: Missing or invalid authentication
```
FORBIDDEN
```
: Insufficient permissions
```
NOT_FOUND
```
: Resource not found
```
VALIDATION_ERROR
```
: Invalid input data
```
RATE_LIMIT_EXCEEDED
```
: Too many requests

All errors follow this format:

json

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": ["Specific error detail"]
  }
}

Common error codes:

```
UNAUTHORIZED
```
: Missing or invalid authentication
```
FORBIDDEN
```
: Insufficient permissions
```
NOT_FOUND
```
: Resource not found
```
VALIDATION_ERROR
```
: Invalid input data
```
RATE_LIMIT_EXCEEDED
```
: Too many requests

Rate Limiting

Rate limit: 1000 requests per hour
Limit resets: Every hour at :00
Headers returned:
- ```
X-RateLimit-Limit
```
  : Total limit
- ```
X-RateLimit-Remaining
```
  : Remaining requests
- ```
X-RateLimit-Reset
```
  : Reset timestamp

---

Rate limit: 1000 requests per hour
Limit resets: Every hour at :00
Headers returned:
- ```
X-RateLimit-Limit
```
  : Total limit
- ```
X-RateLimit-Remaining
```
  : Remaining requests
- ```
X-RateLimit-Reset
```
  : Reset timestamp

---

Documentation Standards

文档规范

Writing Style

写作风格

Use clear, concise language
Avoid jargon or explain when necessary
Write for the target audience (developers vs. end-users)
Use active voice
Provide examples for everything
Keep paragraphs short (3-5 sentences)

使用清晰、简洁的语言
避免行话，必要时加以解释
针对目标受众写作（开发人员vs终端用户）
使用主动语态
为所有内容提供示例
保持段落简短（3-5句话）

Structure

结构

Start with overview/introduction
Include table of contents for long documents
Use clear headings and subheadings
Provide step-by-step instructions
Include troubleshooting section
Add "Next Steps" or "See Also" sections

以概述/介绍开头
长文档包含目录
使用清晰的标题和副标题
提供分步说明
包含故障排除章节
添加“下一步”或“另请参阅”部分

Code Examples

代码示例

Always test code examples
Include complete, runnable examples
Add comments explaining key parts
Show expected output
Cover common use cases

始终测试代码示例
提供完整、可运行的示例
添加注释解释关键部分
展示预期输出
覆盖常见使用场景

Maintenance

维护

Date all documentation
Version documentation with code
Mark deprecated features clearly
Keep examples up to date
Regular review and updates

为所有文档标注日期
文档版本与代码同步
清晰标记已弃用功能
保持示例更新
定期审核与更新

Collaboration Patterns

协作模式

With Architect (or architect-role-skill)

与Architect（或architect-role-skill）协作

Review ARCHITECTURE.md for technical accuracy
Request clarification on design decisions
Ensure documentation reflects actual architecture

审核ARCHITECTURE.md确保技术准确性
请求对设计决策的说明
确保文档反映实际架构

With Builder (or builder-role-skill)

与Builder（或builder-role-skill）协作

Request code walkthroughs for complex features
Verify API examples match implementation
Update docs when code changes

请求复杂功能的代码讲解
验证API示例与实现一致
代码变更时更新文档

With DevOps (or devops-role-skill)

与DevOps（或devops-role-skill）协作

Coordinate on deployment documentation
Verify infrastructure details
Document monitoring and operations procedures

协调部署文档内容
验证基础设施细节
记录监控与运维流程

Examples

示例

Example 1: New Project Documentation

示例1：新项目文档

Task: Create complete documentation suite for new Node.js API

markdown

undefined

任务：为新Node.js API创建完整文档套件

markdown

undefined

Deliverables Created

交付成果

README.md (project overview, quick start)
BUILDING.md (development setup, build process)
DEPLOYMENT.md (Docker, Kubernetes, cloud platforms)
API.md (endpoints, authentication, examples)
CONTRIBUTING.md (contribution guidelines)

Result: Complete documentation enabling new developers to get started within 30 minutes

undefined

README.md（项目概述、快速入门）
BUILDING.md（开发环境搭建、构建流程）
DEPLOYMENT.md（Docker、Kubernetes、云平台部署）
API.md（端点、认证、示例）
CONTRIBUTING.md（贡献指南）

结果：完整文档使新开发人员可在30分钟内上手

undefined

Example 2: API Documentation Update

示例2：API文档更新

Task: Document 15 new API endpoints after feature development

markdown

undefined

任务：功能开发完成后为15个新API端点编写文档

markdown

undefined

Documentation Added

新增文档内容

Endpoint specifications (request/response schemas)
Authentication requirements
Code examples in bash/curl
Error scenarios and handling
Rate limiting details

Result: API documentation coverage increased from 60% to 95%

---

端点规范（请求/响应 schema）
认证要求
bash/curl代码示例
错误场景与处理
限流细节

结果：API文档覆盖率从60%提升至95%

---

Resources

资源

Templates

模板

```
resources/README_template.md
```
- Project README template
```
resources/API_template.md
```
- API documentation template
```
resources/DEPLOYMENT_template.md
```
- Deployment guide template
```
resources/CONTRIBUTING_template.md
```
- Contribution guidelines template

```
resources/README_template.md
```
- 项目README模板
```
resources/API_template.md
```
- API文档模板
```
resources/DEPLOYMENT_template.md
```
- 部署指南模板
```
resources/CONTRIBUTING_template.md
```
- 贡献指南模板

Style Guides

风格指南

References

参考

Agent Skills vs. Multi-Agent
Markdown Guide
API Documentation Best Practices

Version: 1.0.0 Last Updated: December 12, 2025 Status: ✅ Active Maintained By: Claude Command and Control Project

Agent Skills vs. Multi-Agent
Markdown Guide
API Documentation Best Practices

Version: 1.0.0 Last Updated: December 12, 2025 Status: ✅ Active Maintained By: Claude Command and Control Project

scribe-role-skill

Original

Translation

Scribe Role Skill

Scribe角色技能

Description

描述

When to Use This Skill

何时使用此技能

When NOT to Use This Skill

何时不使用此技能

Prerequisites

前提条件

Workflow

工作流

Phase 1: Comprehensive Project Documentation

第一阶段：全面项目文档

Understand project structure

Understand project structure

Identify main entry points

Identify main entry points

Review package manifest

Review package manifest

Check existing documentation

Check existing documentation

Documentation Plan: [Project Name]

Documentation Plan: [Project Name]

Current State Assessment

当前状态评估

Documentation Structure

文档结构

Priority

优先级

Timeline

时间线

README.md Template

README.md模板

[Project Name]

[Project Name]

Overview

概述

Quick Start

快速入门

Clone the repository

Clone the repository

Install dependencies

Install dependencies

Run the application

Run the application

Features

功能特性

Documentation

文档

Requirements

环境要求

Installation

安装

Usage

使用

Contributing

贡献

License

许可证

Support

支持

Credits

致谢

BUILDING.md Template

BUILDING.md模板

Building [Project Name]

Building [Project Name]

Prerequisites

Prerequisites

Required Tools

Required Tools

Optional Tools

Optional Tools

Environment Setup

Environment Setup

macOS