scribe-role-skill
Professional technical writing and documentation skill for creating andmaintaining comprehensive, accurate, and user-friendly documentation forcodebases, APIs, deployment processes, and end-user guides.
When & Why to Use This Skill
The Scribe Role Skill is a professional technical writing and documentation assistant designed to streamline the creation and maintenance of high-quality project documentation. It automates the generation of comprehensive README files, API references, deployment guides, and user manuals, ensuring that codebases remain accessible, maintainable, and easy to navigate for both developers and end-users.
Use Cases
- Project Onboarding: Automatically generating a complete documentation suite (README, BUILDING, DEPLOYMENT) for new software repositories to accelerate developer setup.
- API Documentation: Creating detailed API references including endpoint specifications, authentication methods, and runnable code examples.
- DevOps & Deployment Guides: Writing step-by-step instructions for deploying applications across various environments like Docker, Kubernetes, and major cloud providers (AWS/GCP/Azure).
- Maintenance & Auditing: Analyzing existing codebases to identify documentation gaps and updating outdated technical guides to reflect current implementation.
- User & Contributor Support: Developing user manuals, troubleshooting guides, and contribution guidelines to improve project adoption and community collaboration.
| name | scribe-role-skill |
|---|---|
| version | 1.0.0 |
| category | documentation |
| complexity | moderate |
| status | active |
| created | 2025-12-12 |
| author | claude-command-and-control |
| description | | |
| dependencies | [] |
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
```bash
# 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
Requirements
- [Runtime/Language]: version X.X+
- [Database]: version Y.Y+ (if applicable)
- [Other dependencies]
Installation
See GETTING_STARTED.md for detailed installation instructions.
Usage
See USAGE.md for comprehensive usage documentation.
Contributing
See 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
```markdown
# 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
```bash
# 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 variableswebpack.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
mainbranch: Production build - Push to
developbranch: Development build - Pull requests: Test build
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
--parallelflag
Next Steps
After building, see:
- DEPLOYMENT.md for deployment instructions
- TESTING.md for running tests
#### DEPLOYMENT.md Template
```markdown
# 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:
```bash
# 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
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 for observability setup
- Configure BACKUP.md procedures
- Set up ALERTS.md for critical issues
---
### Phase 2: API Documentation
Create comprehensive API reference documentation.
**Step 2.1: Create API.md**
```markdown
# 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:
```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
https://api.example.com/v1/endpoint
Obtaining a Token
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:
{
"id": "123",
"email": "user@example.com",
"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": "user@example.com",
"password": "SecurePass123!",
"name": "John Doe"
}
Response: 201 Created
{
"id": "124",
"email": "user@example.com",
"name": "John Doe",
"created_at": "2025-11-10T00:00:00Z"
}
Errors:
400 Bad Request: Invalid input409 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 authenticationFORBIDDEN: Insufficient permissionsNOT_FOUND: Resource not foundVALIDATION_ERROR: Invalid input dataRATE_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 limitX-RateLimit-Remaining: Remaining requestsX-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
```markdown
## 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 templateresources/API_template.md- API documentation templateresources/DEPLOYMENT_template.md- Deployment guide templateresources/CONTRIBUTING_template.md- Contribution guidelines template
Style Guides
References
Version: 1.0.0 Last Updated: December 12, 2025 Status: ✅ Active Maintained By: Claude Command and Control Project