cyberarian

The digital librarian for Claude Code projects. Enforces structured document lifecycle management - organizing, indexing, and archiving project documentation automatically. Use when creating, organizing, or managing project documentation. Ensures documents are created in the proper `docs/` directory structure with required metadata, handles temporary documents in system temp directories, maintains an auto-generated index, and performs automatic archiving of old/complete documents. Use for any task involving document creation, organization, or maintenance.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️2downloads

When & Why to Use This Skill

Cyberarian is a comprehensive document lifecycle management skill designed for Claude Code projects. It acts as a digital librarian by enforcing a structured documentation hierarchy, managing metadata through YAML frontmatter, and automating the indexing and archiving of project files. A standout feature is its 'Subagent Delegation' pattern, which offloads verbose document operations to isolated contexts, keeping the main agent's reasoning window clean and efficient. This skill ensures that project knowledge remains organized, discoverable, and maintainable throughout the software development lifecycle.

Use Cases

  • Automated Project Documentation: Automatically organizing technical specs, implementation plans, and bug analyses into a standardized 'docs/' directory with required metadata.
  • Context-Efficient Maintenance: Delegating heavy tasks like bulk metadata validation or full-index regeneration to subagents to prevent context pollution in the main conversation.
  • Document Lifecycle Automation: Implementing automatic archiving policies for completed or outdated documents based on status and age to keep the active workspace clutter-free.
  • Knowledge Base Discovery: Maintaining an auto-generated INDEX.md that provides a searchable, categorized map of all project documentation for both human developers and AI agents.
  • Standardized Documentation Workflow: Using built-in templates and scripts to ensure every new document follows project-wide naming conventions and metadata requirements.
namecyberarian
descriptionThe digital librarian for Claude Code projects. Enforces structured document lifecycle management - organizing, indexing, and archiving project documentation automatically. Use when creating, organizing, or managing project documentation. Ensures documents are created in the proper `docs/` directory structure with required metadata, handles temporary documents in system temp directories, maintains an auto-generated index, and performs automatic archiving of old/complete documents. Use for any task involving document creation, organization, or maintenance.

Cyberarian - Document Lifecycle Management

This skill enforces a structured approach to documentation in Claude Code projects, ensuring consistency, discoverability, and automatic maintenance.

Core Principles

  1. Structured Organization: All persistent documentation goes in docs/ with semantic categorization
  2. No Temporary Docs in docs/: Ephemeral/scratch documents belong in /tmp or system temp, never in docs/
  3. Metadata-Driven: YAML frontmatter enables automation and lifecycle management
  4. Automatic Maintenance: Indexing and archiving happen automatically, not manually
  5. Context Efficiency: Bulk operations delegate to subagents to preserve main context

Context-Efficient Operations

The Problem

Document management operations can produce verbose output that pollutes the main agent's context:

  • Validation scripts listing many errors across files
  • Index generation scanning dozens of documents
  • Archive operations listing all files being moved
  • Search results returning many matches

The Solution: Subagent Delegation

Delegate to Task subagent for operations that return verbose output. The subagent absorbs the verbose output in its isolated context and returns a concise summary (<50 tokens).

Delegation Rules

Execute directly (simple, low-output):

  • Creating a single document from template
  • Reading a specific document's metadata
  • Checking if docs/ directory exists

Delegate to Task subagent (complex, verbose):

  • Running validation across all documents
  • Regenerating the index
  • Archiving operations (especially dry-run)
  • Searching documents by tag/status/category
  • Summarizing INDEX.md contents
  • Any operation touching multiple files

Delegation Pattern

When verbose output is expected:

1. Recognize the operation will be verbose
2. Delegate to Task subagent with explicit instructions
3. Subagent executes scripts, absorbs output
4. Subagent parses and returns summary <50 tokens
5. Main agent receives only essential summary

Task subagent prompt format:

Execute document operation and return concise summary:
- Run: [command]
- Parse: Extract [specific data needed]
- Return: [emoji] [state] | [metric] | [next action]
- Limit: <50 tokens

Use agents/doc-librarian-subagent.md patterns for response formatting.

Response Formats

Success: ✓ [result] | [metric] | Next: [action] List: 📋 [N] items: [item1], [item2], ... (+[remainder] more) Error: ❌ [operation] failed | Reason: [brief] | Fix: [action] Warning: ⚠️ [concern] | Impact: [brief] | Consider: [action]

Directory Structure

docs/
├── README.md           # Human-written guide to the structure
├── INDEX.md            # Auto-generated index of all documents
├── ai_docs/           # Reference materials for Claude Code (SDKs, APIs, repo context)
├── specs/             # Feature and migration specifications
├── analysis/          # Investigation outputs (bugs, optimization, cleanup)
├── plans/             # Implementation plans
├── templates/         # Reusable templates
└── archive/           # Historical and completed documents
    ├── specs/
    ├── analysis/
    └── plans/

Workflows

First-Time Setup

When a project doesn't have a docs/ directory:

  1. Initialize the structure:

    python scripts/init_docs_structure.py
    

    This creates all directories, README.md, and initial INDEX.md

  2. Inform the user about the structure and conventions

Creating a New Document

When asked to create documentation (specs, analysis, plans, etc.):

  1. Determine the category:

    • ai_docs: SDKs, API references, repo architecture, coding conventions
    • specs: Feature specifications, migration plans, technical designs
    • analysis: Bug investigations, performance analysis, code audits
    • plans: Implementation plans, rollout strategies, task breakdowns
    • templates: Reusable document templates
  2. Use the template:

    cp assets/doc_template.md docs/<category>/<descriptive-name>.md
    
  3. Fill in metadata:

    • Set title, category, status, created, last_updated
    • Add relevant tags
    • Start with status: draft
  4. Write the content following the document structure

  5. Update the index:

    python scripts/index_docs.py
    

File naming convention: Use lowercase with hyphens, descriptive names:

  • ✅ oauth2-migration-spec.md
  • ✅ auth-performance-analysis.md
  • ❌ spec1.md
  • ❌ MyDocument.md

Working with Existing Documents

When modifying existing documentation:

  1. Update metadata:

    • Set last_updated to current date
    • Update status if lifecycle changes (draft → active → complete)
  2. Regenerate index if significant changes:

    python scripts/index_docs.py
    

Creating Temporary/Scratch Documents

When creating ephemeral documents (scratchpads, temporary notes, single-use docs):

NEVER create in docs/ - Use system temp instead:

# Create in /tmp for Linux/macOS
/tmp/scratch-notes.md
/tmp/debug-output.txt

# Let the system clean up temporary files

Why: The docs/ directory is for persistent, managed documentation. Temporary files clutter the structure and interfere with indexing and archiving.

Regular Maintenance

When to run:

  • After creating/modifying documents: Update index
  • Weekly/monthly: Run archiving to clean up completed work
  • Before commits: Validate metadata

Maintenance workflow (delegate to Task subagent for context efficiency):

  1. Validate metadata → Delegate to subagent:

    Task: Run python scripts/validate_doc_metadata.py
    Return: ✓ [N] valid | [N] issues: [list top 3] | Next: [action]
    
  2. Archive old documents → Delegate to subagent:

    Task: Run python scripts/archive_docs.py --dry-run
    Return: 📦 [N] ready for archive: [list top 3] | Next: Run archive
    
    Task: Run python scripts/archive_docs.py
    Return: ✓ Archived [N] docs | Categories: [list] | Index updated
    
  3. Update index → Delegate to subagent:

    Task: Run python scripts/index_docs.py
    Return: ✓ Index updated | [N] documents | Categories: [summary]
    

Why delegate? These operations can scan dozens of files and produce verbose output. Subagent isolation keeps the main context clean for reasoning.

Archiving Documents

Archiving happens automatically based on category-specific rules. See references/archiving-criteria.md for full details.

Quick reference:

  • specs/: Auto-archive when status: complete AND >90 days
  • analysis/: Auto-archive when status: complete AND >60 days
  • plans/: Auto-archive when status: complete AND >30 days
  • ai_docs/: Manual archiving only
  • templates/: Never auto-archive

To prevent auto-archiving, set in frontmatter:

archivable_after: 2025-12-31

Metadata Requirements

Every document must have YAML frontmatter. See references/metadata-schema.md for complete schema.

Minimal required frontmatter:

---
title: Document Title
category: specs
status: draft
created: 2024-11-16
last_updated: 2024-11-16
tags: []
---

Lifecycle statuses:

  • draft → Document being created
  • active → Current and relevant
  • complete → Work done, kept for reference
  • archived → Moved to archive

Reference Files

Load these when needed for detailed guidance:

  • references/metadata-schema.md: Complete YAML frontmatter specification
  • references/archiving-criteria.md: Detailed archiving rules and philosophy
  • agents/doc-librarian-subagent.md: Subagent template for context-efficient operations

Scripts Reference

All scripts accept optional path argument (defaults to current directory):

  • scripts/init_docs_structure.py [path] - Initialize docs structure
  • scripts/index_docs.py [path] - Regenerate INDEX.md
  • scripts/archive_docs.py [path] [--dry-run] - Archive old documents
  • scripts/validate_doc_metadata.py [path] - Validate all metadata

Common Patterns

Creating a Specification

# Copy template
cp assets/doc_template.md docs/specs/new-feature-spec.md

# Edit with proper metadata
# category: specs
# status: draft
# tags: [feature-name, relevant-tags]

# Update index
python scripts/index_docs.py

Completing Work

# Update document metadata
# status: draft → active → complete
# last_updated: <current-date>

# After a while, archiving script will auto-archive
python scripts/archive_docs.py

Finding Documents

Delegate searches to subagent for context efficiency:

Task: Summarize docs/INDEX.md
Return: 📊 [N] total docs | Categories: [breakdown] | Recent: [latest doc]

Task: Search docs for tag "performance"
Run: grep -r "tags:.*performance" docs/ --include="*.md" | head -10
Return: 📋 [N] docs match: [path1], [path2], ... | Next: Read [most relevant]

Task: Find all draft documents
Run: grep -r "status: draft" docs/ --include="*.md"
Return: 📋 [N] drafts: [list top 5] | Next: [action]

Direct execution (only for quick checks):

# Check if docs/ exists
ls docs/ 2>/dev/null

Best Practices

  1. Always use metadata: Don't skip the frontmatter, it enables automation
  2. Keep status current: Update as work progresses (draft → active → complete)
  3. Use descriptive names: File names should be clear and searchable
  4. Update dates: Set last_updated when making significant changes
  5. Run maintenance regularly: Index and archive periodically
  6. Temp goes in /tmp: Never create temporary/scratch docs in docs/
  7. Validate before committing: Run validate_doc_metadata.py to catch issues
  8. Delegate bulk operations: Use Task subagents for validation, indexing, archiving, and search to preserve main context

Error Handling

Document has no frontmatter:

  • Add frontmatter using assets/doc_template.md as reference
  • Run validate_doc_metadata.py to confirm

Document in wrong category:

  • Move file to correct category directory
  • Update category field in frontmatter to match
  • Regenerate index

Archived document still needed:

  • Move from archive/<category>/ back to <category>/
  • Update status from archived to active
  • Remove archived_date and archive_reason fields
  • Regenerate index