Scribe Role Skill

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.

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

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)

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

Workflow

Phase 1: Comprehensive Project Documentation

Create complete documentation suite for a project.

Step 1.1: Codebase Analysis

# 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:

# 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

## Priority

1. **Critical (Must Have)**:
   - README.md
   - BUILDING.md
   - DEPLOYMENT.md

2. **Important (Should Have)**:
   - API.md
   - USAGE.md
   - TROUBLESHOOTING.md

3. **Nice to Have**:
   - ARCHITECTURE.md (if not done by architect)
   - CONTRIBUTING.md
   - Advanced guides

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

Step 1.3: Create Core Documentation

README.md Template

# [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?]

## Quick Start

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.

## Features

- **Feature 1**: Description
- **Feature 2**: Description
- **Feature 3**: Description

## Documentation

- [Getting Started Guide](docs/GETTING_STARTED.md)
- [Building Instructions](docs/BUILDING.md)
- [Deployment Guide](docs/DEPLOYMENT.md)
- [API Documentation](docs/API.md)
- [User Manual](docs/USAGE.md)

## Requirements

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

## Installation

See [GETTING_STARTED.md](docs/GETTING_STARTED.md) for detailed installation instructions.

## Usage

See [USAGE.md](docs/USAGE.md) for comprehensive usage documentation.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.

## License

[License type and link]

## Support

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

## Credits

[Acknowledgments, authors, contributors]

BUILDING.md Template

# 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])

### Optional Tools
- [Tool]: For [purpose]

## Environment Setup

### macOS

Install dependencies

brew install [package1] [package2]

Set environment variables

export VAR_NAME=value

### Linux (Ubuntu/Debian)

Install dependencies

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

Set environment variables

export VAR_NAME=value

### Windows

Install dependencies using chocolatey

choco install [package1] [package2]

Set environment variables

$env:VAR_NAME="value"

## Building the Application

### Development Build

Install dependencies

npm install # or equivalent

Build for development

npm run build:dev

Output location: ./dist/

### Production Build

Clean previous builds

npm run clean

Install production dependencies

npm ci --production

Build optimized version

npm run build:prod

Output location: ./dist/production/

### 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:

{ 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

## Build Troubleshooting

### Common Issues

**Issue**: Build fails with "out of memory" error

Solution: Increase Node memory limit

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

**Issue**: Dependency resolution fails

Solution: Clear cache and reinstall

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

**Issue**: Module not found errors

Solution: Verify all dependencies installed

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

## 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: [![Build Status](badge-url)](ci-url)

## 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

## Next Steps

After building, see:
- [DEPLOYMENT.md](DEPLOYMENT.md) for deployment instructions
- [TESTING.md](TESTING.md) for running tests

DEPLOYMENT.md Template

# 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 |

## Prerequisites

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

### Environment Variables

Create `.env.[environment]` file:

Application

NODEENV=production PORT=3000 LOGLEVEL=info

Database

DATABASEURL=postgresql://user:pass@host:5432/dbname DATABASEPOOL_SIZE=10

API Keys (use secrets manager in production)

APIKEY=your-api-key SECRETKEY=your-secret-key

Feature Flags

FEATUREXENABLED=true

## Deployment Methods

### Method 1: Manual Deployment

**Step 1: Prepare Application**

Build production artifacts

npm run build:prod

Verify build

ls -la dist/

**Step 2: Deploy to Server**

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**

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

### Method 2: Docker Deployment

**Step 1: Build Docker Image**

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**

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

### Method 3: Kubernetes Deployment

**Step 1: Prepare Kubernetes Manifests**

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**

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

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

#### AWS Elastic Beanstalk

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

#### Google Cloud Platform

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

#### Azure App Service

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

## Post-Deployment Verification

### Health Checks

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

### Smoke Tests

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"

### Monitoring Setup
- 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

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

### Kubernetes Rollback

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

## Troubleshooting

### Deployment Fails

**Check**: Build artifacts

ls -la dist/

Verify all necessary files present

**Check**: Environment variables

printenv | grep APP_

Verify all required variables set

**Check**: Server logs

tail -f /var/log/app/error.log

### Application Not Responding

**Check**: Service status

sudo systemctl status app-service

**Check**: Port bindings

sudo netstat -tulpn | grep :3000

**Check**: Firewall rules

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

## Next Steps

After deployment:
- Review [MONITORING.md](MONITORING.md) for observability setup
- Configure [BACKUP.md](BACKUP.md) procedures
- Set up [ALERTS.md](ALERTS.md) for critical issues

Phase 2: API Documentation

Create comprehensive API reference documentation.

Step 2.1: Create API.md

# API Documentation

## Base URL

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:

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

### Obtaining a Token

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

{ "email": "[email protected]", "password": "password" }

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

## Endpoints

### Users

#### Get User

GET /users/:id

**Parameters**:
- `id` (path, required): User ID

**Response**:

{ "id": "123", "email": "[email protected]", "name": "John Doe", "created_at": "2025-01-01T00:00:00Z" }

**Example**:

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

#### Create User

POST /users

**Request Body**:

{ "email": "[email protected]", "password": "SecurePass123!", "name": "John Doe" }

**Response**: `201 Created`

{ "id": "124", "email": "[email protected]", "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:

{ "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

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)

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)

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

With Builder (or builder-role-skill)

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

With DevOps (or devops-role-skill)

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

Examples

Example 1: New Project Documentation

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

## 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

Example 2: API Documentation Update

Task: Document 15 new API endpoints after feature development

## 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%

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

Style Guides

• Google Developer Documentation Style Guide
• Microsoft Writing Style Guide
• Write the Docs

References

• [Agent Skills vs. Multi-Agent](../../docs/best-practices/09-Agent-Skills-vs-Multi-Agent.md)
• Markdown Guide
• API Documentation Best Practices

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