Clawd Docs

Documentation generation and management system for ClawdBot projects. Automates the creation and maintenance of comprehensive documentation from code analysis, commit history, and TypeScript definitions.

Purpose

This skill eliminates manual documentation overhead by:

• Automatically extracting documentation from TypeScript/JSDoc comments
• Generating API references from type definitions and function signatures
• Creating user-friendly guides from code patterns
• Maintaining changelogs from git commit history
• Building skill documentation with examples and usage patterns
• Keeping README files synchronized with actual implementation

When to Use This Skill

• Generating API documentation from TypeScript interfaces and function types
• Creating comprehensive README files for new projects or major releases
• Documenting newly created skills with examples and capabilities
• Extracting JSDoc comments into formatted markdown documentation
• Maintaining changelogs from git commit history (pairs with changelog-generator)
• Building reference documentation for integrations and adapters
• Documenting external API schemas and integration patterns
• Creating skill documentation with examples and trigger conditions
• Building architecture documentation from code structure analysis
• Generating parameter and return type documentation

What This Skill Does

Code Analysis & Extraction

1. JSDoc Parsing: Extracts and formats JSDoc comments from TypeScript/JavaScript files
2. Type Analysis: Generates reference documentation from TypeScript type definitions and interfaces
3. Function Signatures: Documents all functions with parameters, return types, and examples
4. Export Analysis: Identifies public APIs and export patterns

Documentation Generation

1. API Reference: Creates structured API documentation with examples
2. Type Definitions: Generates documentation for all TypeScript types and interfaces
3. Function Documentation: Creates detailed function references with parameters and return types
4. Example Extraction: Pulls and formats code examples from JSDoc annotations
5. Integration Guides: Documents integration patterns and usage examples

File Management

1. README Generation: Creates or updates comprehensive README files
2. Changelog Maintenance: Integrates with git history for version tracking
3. Skill Documentation: Auto-generates skill SKILL.md files with examples
4. Architecture Docs: Creates project structure and pattern documentation
5. File Organization: Manages documentation hierarchy and cross-references

Quality Assurance

1. Documentation Validation: Ensures all public exports are documented
2. Example Verification: Validates that code examples are syntactically correct
3. Link Checking: Verifies internal documentation links and references
4. Completeness Audit: Reports missing documentation and type annotations

How to Use

Generate API Documentation

From your project repository:

Generate API documentation from src/api.ts, save to docs/API.md

Create TypeScript type definitions documentation for all types in src/types.ts

Extract and document all functions exported from src/index.ts

Create or Update README Files

Generate a comprehensive README.md for this project based on package.json and source code

Update README.md with current API endpoints and integration examples

Create README documentation for the current skill, including examples

Document New Skills

Generate skill documentation (SKILL.md) for this new skill including triggers,
capabilities, usage examples, and integration points

Create comprehensive skill docs with examples showing how to invoke this skill
and what it returns

Maintain Changelogs

Generate a changelog from git commits since the last release, categorized by type

Update CHANGELOG.md with commits from the past week, using semantic versioning

Extract Code Documentation

Extract all JSDoc comments from src/ directory and create docs/REFERENCE.md

Generate function documentation for all exported functions in src/lib/

Integration Documentation

Document the Plaid integration pattern, including OAuth flow, token storage, and API usage

Create integration guide for the database adapter, showing schema and usage patterns

Capabilities

File Type Support

• TypeScript (.ts, .tsx)
• JavaScript (.js, .jsx)
• JSX/React Components
• JSON schemas and configurations
• Markdown documentation files
• Package.json and project metadata

Documentation Formats

• API Reference Documentation
• TypeScript Type Definitions Reference
• Function Parameter & Return Type Documentation
• Code Example Extraction & Formatting
• Changelog Generation
• README Templates
• Skill Documentation
• Architecture Guides
• Integration Patterns

Analysis Types

• JSDoc Comment Extraction
• TypeScript Type Analysis
• Function Signature Documentation
• Export Pattern Identification
• Code Example Detection
• Dependency Documentation
• Configuration Documentation
• Error Handling Patterns

Integration

• Git commit history analysis
• Package.json metadata extraction
• TypeScript compiler integration
• Markdown formatting and validation
• Cross-reference linking
• Version management

Examples

Example 1: Generate API Documentation

User Request: “Generate API documentation from my TypeScript functions”

Input:

/**
 * Encrypts an OAuth token using AES-256-GCM
 * @param plaintext - The token to encrypt
 * @returns Base64-encoded encrypted token (IV + AuthTag + Ciphertext)
 * @throws CryptoError if encryption fails
 */
export function encryptToken(plaintext: string): string {
  // implementation
}

/**
 * Decrypts an encrypted OAuth token
 * @param encrypted - Base64-encoded encrypted token
 * @returns Decrypted plaintext token
 * @throws CryptoError if decryption fails
 */
export function decryptToken(encrypted: string): string {
  // implementation
}

Output (docs/CRYPTO.md):

# Encryption API Reference

## encryptToken

Encrypts an OAuth token using AES-256-GCM

### Parameters
- `plaintext: string` - The token to encrypt

### Returns
`string` - Base64-encoded encrypted token (IV + AuthTag + Ciphertext)

### Throws
`CryptoError` - if encryption fails

### Example
```typescript
const token = '...oauth_token...';
const encrypted = encryptToken(token);
// Returns: "base64EncodedEncryptedToken"

decryptToken

Decrypts an encrypted OAuth token

Parameters

• encrypted: string – Base64-encoded encrypted token

Returns

string – Decrypted plaintext token

Throws

CryptoError – if decryption fails

Example

const encrypted = '...encrypted_token...';
const plaintext = decryptToken(encrypted);
// Returns: original token

### Example 2: Create Skill Documentation

**User Request**: "Generate SKILL.md documentation for the new analyzer skill"

**Output** (skills/analyzer/SKILL.md):
```markdown
---
name: analyzer
description: |
  Analyzes code patterns and generates optimization suggestions. Use when:
  (1) reviewing code quality, (2) identifying performance bottlenecks,
  (3) suggesting refactoring opportunities.
author: Your Name
version: 1.0.0
---

# Analyzer Skill

Comprehensive code analysis and optimization suggestion system.

## When to Use

- Analyzing code quality metrics
- Identifying performance issues
- Suggesting refactoring improvements
- Finding code smell patterns
- Detecting security vulnerabilities

## What It Does

1. **Pattern Recognition**: Identifies common code patterns and anti-patterns
2. **Performance Analysis**: Detects performance bottlenecks
3. **Quality Metrics**: Calculates code quality scores
4. **Suggestions**: Provides specific, actionable improvements

## How to Use

Analyze src/api.ts for performance issues

Review this React component for optimization opportunities

## Examples

[Examples with actual code]

Example 3: Update README with Type Definitions

User Request: “Update README.md to include API type definitions”

Input File: src/types.ts with multiple interfaces

Output: Updated README.md section documenting all exported types with usage examples

Example 4: Generate Changelog from Commits

User Request: “Create a changelog for v1.5.0 release”

Output (CHANGELOG.md entry):

## [1.5.0] - 2024-03-15

### Added
- New encryption utilities for token storage
- API documentation generation system
- Skill documentation templates

### Changed
- Improved error reporting in database migrations
- Enhanced OAuth token validation

### Fixed
- Fixed token expiration date calculation
- Resolved cross-reference linking in documentation

Tips

• Run from your project root directory
• JSDoc comments should follow standard format for best results
• Keep TypeScript files well-typed for comprehensive API docs
• Use git commits with conventional commit format for better changelogs
• Review generated documentation before publishing
• Update JSDoc comments when APIs change
• Use cross-reference linking for better navigation
• Run after major code changes to keep docs synchronized

Related Use Cases

• Creating GitHub release notes (see changelog-generator)
• Documenting API integrations
• Building library reference documentation
• Creating onboarding guides for new developers
• Generating API client documentation
• Creating SDK documentation
• Building architecture decision records (ADRs)
• Documenting database schemas and migrations

Patterns Supported

OAuth Integration Patterns

Documents OAuth flows, token storage, and refresh mechanisms

Database Adapter Patterns

Documents schema, migrations, and query patterns

Skill Implementation Patterns

Documents skill structure, triggers, and capabilities

CLI Tool Patterns

Documents command structure, flags, and examples

API Endpoint Patterns

Documents endpoint definitions, parameters, and responses

Type Definition Patterns

Documents TypeScript interfaces, types, and enums

Error Handling Patterns

Documents error types and handling strategies

Output Examples

• docs/API.md – Complete API reference
• docs/TYPES.md – TypeScript type definitions reference
• README.md – Project overview and getting started
• CHANGELOG.md – Release history with semantic versioning
• skills/[skill-name]/SKILL.md – Skill documentation
• docs/INTEGRATIONS.md – Integration guides
• docs/ARCHITECTURE.md – System design and patterns