home / skills / ladderchaos / tora-skills / repo-librarian

repo-librarian skill

safe

This skill cleans cluttered repos by eliminating dead code, organizing markdown, and keeping documentation synced to streamline maintenance and releases.

npx playbooks add skill ladderchaos/tora-skills --skill repo-librarian

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.8 KB

---
name: repo-librarian
description: Repository cleanup, documentation management, and markdown reorganization. Use this skill when the repo feels cluttered, documentation is scattered, or after major version upgrades. Handles dead code elimination, legacy artifact removal, and documentation indexing.
---

# Repository Librarian

Responsible for the structural integrity, cleanliness, and documentation of repositories.

## When This Skill Activates

- Repo feels "cluttered" with old files
- Documentation is scattered and hard to find
- After major version upgrades
- Before major releases (cleanup)
- Dead code or legacy artifacts detected

## Responsibilities

### 1. Repository Cleaning
- **Dead Code Elimination**: Identify and remove unused functions, variables, and imports
- **Legacy Artifact Removal**: Delete or archive files no longer part of current architecture
- **Redundant Component Purging**: Consolidate multiple implementations of same feature

### 2. Documentation Management
- **Code Documentation**: Maintain function/method docs and type annotations
- **Knowledge Files**: Keep KNOWLEDGE.md, GUIDE.md in sync with code
- **ADR Maintenance**: Ensure DECISIONS.md reflects recent architectural choices

### 3. Markdown Reorganization
- **Audit & Reorganize**: Periodically review all `.md` files
- **Archiving**: Move superseded documentation to archives
- **Indexing**: Maintain clear documentation index in README

## Workflow: Markdown Reorganization

1. **Inventory**: List all `.md` files
2. **Read & Categorize**: Determine status (Active, Superseded, Research, Spec)
3. **Analyze Redundancy**: Identify overlapping content
4. **Propose Structure**: Draft new directory structure
5. **Execute**: Move files, update internal links, update index

## Operating Principles

- **Alpha Mode**: Prioritize speed and clarity. Deletion preferred over zombie docs
- **Verification**: Use grep to check for references before deleting
- **Change Tracking**: Document major purges in CHANGELOG

## Cleanup Actions

When cleaning up, follow this order:

1. **Identify** - List what needs cleanup
2. **Verify unused** - Confirm no code depends on it
3. **Archive if valuable** - Move to `.archive/` if historically important
4. **Delete if not** - Remove outright if truly obsolete
5. **Update imports** - Fix any broken references
6. **Test** - Ensure nothing broke

## Quick Commands

```bash
# Find all markdown files
find . -name "*.md" -type f | grep -v node_modules

# Find large commented blocks
grep -rn "^//" --include="*.sol" --include="*.ts" | wc -l

# Check for stale imports
npx depcheck

# Find TODO/FIXME
grep -rn "TODO\|FIXME" --include="*.sol" --include="*.ts"
```

## Anti-Patterns

- Moving files without updating links
- Keeping multiple versions without clear "Active" labels
- Deleting dynamically referenced code
- Over-organizing (sometimes "good enough" is perfect)

Overview

This skill cleans and reorganizes a codebase to improve structural integrity, remove legacy artifacts, and centralize documentation. It focuses on dead code elimination, documentation indexing, and markdown reorganization to make the project easier to navigate and maintain. Use it after major upgrades or when the codebase feels cluttered to restore clarity and reduce technical debt.

How this skill works

The skill scans the codebase for unused functions, variables, imports, and legacy files, then verifies references before removal. It inventories all markdown files, categorizes them (Active, Superseded, Research, Spec), and proposes a streamlined directory structure. Execution includes moving or archiving files, updating internal links and indexes, and recording major purges in a changelog. Final steps update imports and run tests to ensure nothing breaks.

When to use it

After major version upgrades that leave behind legacy artifacts
When documentation is scattered or difficult to locate
Before a major release to reduce clutter and technical debt
When dead code or redundant implementations are suspected
During periodic housekeeping to maintain long-term clarity

Best practices

Always verify references (grep/depcheck) before deleting code or docs
Archive historically valuable files under a clear .archive/ area rather than immediate deletion
Keep a documented index of active documentation and update it when moving files
Prefer simple, consistent labels like Active/Superseded to avoid multiple ambiguous versions
Run unit and integration tests after cleanup to detect broken imports or regressions

Example use cases

Consolidating multiple how-to guides into a single indexed Docs folder and archiving older drafts
Removing unused modules and updating imports after a refactor to trim build size
Auditing markdown to remove duplication, updating internal links, and creating a top-level documentation index
Cleaning out legacy config or tooling files left from previous architecture choices
Maintaining DECISIONS.md or ADRs to reflect recent architectural changes

FAQ

What if a file appears unused but is referenced dynamically?

Verify with runtime checks, search patterns for dynamic loading, and conservative archiving rather than deletion until confirmed safe.

How do you handle many overlapping docs?

Categorize by status, merge active content into a single canonical document, and move superseded material to an archive with cross-links.