Agent skill

cleanup-project

Project cleanup and pruning workflow. Use when removing unused guides, cleaning up stale components, or streamlining an Samuel installation to match actual project needs.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/cleanup-project

Metadata

Additional technical details for this skill

author
samuel
version
1.0
category
workflow

SKILL.md

Project Cleanup Workflow

When to Use

Trigger Description
Post-Initialization After initialize-project.md completes
Quarterly Maintenance Every 3 months as part of project hygiene
Pre-Release Before major releases to reduce deployment footprint
Size Threshold When .claude/ exceeds 1MB
Stack Change After removing a language/framework from the project

Prerequisites

Before starting cleanup:

  • Project has been initialized (CLAUDE.md exists or stack is clear)
  • No active development in progress that might need guides being pruned
  • Git working directory is clean (commit or stash changes first)

Process Overview

Step 1: Analyze Project Stack
    ↓
Step 2: Prune Unused Guides
    ↓
Step 3: Archive Stale Tasks
    ↓
Step 4: Consolidate Memory
    ↓
Step 5: Clean Patterns
    ↓
Step 6: Update Documentation
    ↓
Output: Leaner .claude/ directory

Step 1: Analyze Project Stack

1.1 Detect Active Languages

Scan project files to identify which languages are actually used:

File Language
package.json TypeScript/JavaScript
tsconfig.json TypeScript
requirements.txt, pyproject.toml, setup.py Python
go.mod Go
Cargo.toml Rust
build.gradle.kts, *.kt Kotlin
pom.xml, build.gradle, *.java Java
*.csproj, *.sln C#
composer.json PHP
Package.swift, *.swift Swift
CMakeLists.txt, Makefile, *.cpp, *.c C/C++
Gemfile, *.rb Ruby
pubspec.yaml Dart

AI Action: List all detected languages based on project files.

1.2 Detect Active Frameworks

Check dependency files for framework usage:

Node.js/TypeScript (package.json dependencies):

  • react, react-dom → React
  • next → Next.js
  • express → Express

Python (requirements.txt, pyproject.toml):

  • django → Django
  • fastapi → FastAPI
  • flask → Flask

Go (go.mod):

  • github.com/gin-gonic/gin → Gin
  • github.com/labstack/echo → Echo
  • github.com/gofiber/fiber → Fiber

Rust (Cargo.toml):

  • axum → Axum
  • actix-web → Actix-web
  • rocket → Rocket

(Continue for all language families)

AI Action: List all detected frameworks based on dependencies.

1.3 Generate Active Guides Manifest

Create .claude/active-guides.json:

json
{
  "generated": "2025-01-15T10:00:00Z",
  "languages": [
    "typescript"
  ],
  "frameworks": [
    "react",
    "nextjs"
  ],
  "guides_kept": [
    "skills/typescript-guide/SKILL.md",
    "skills/react/SKILL.md",
    "skills/nextjs/SKILL.md"
  ],
  "guides_archived": [
    "skills/python-guide/SKILL.md",
    "skills/go-guide/SKILL.md",
    "..."
  ]
}

AI Action: Create active-guides.json with detected stack.

Step 2: Prune Unused Guides

2.1 Identify Unused Guides

Compare existing guides against active-guides.json:

All Language Guides: 21
Active Languages: 1 (TypeScript)
Unused Guides: 20 (95% reduction possible)

All Framework Skills: 33
Active Frameworks: 2 (React, Next.js)
Unused Skills: 31 (94% reduction possible)

2.2 Archive Strategy (Recommended)

Move unused guides to .claude/.archive/ for potential future use:

bash
# Create archive directories
mkdir -p .claude/.archive/skills

# Move unused language guide skills
mv .claude/skills/python-guide/ .claude/.archive/skills/
mv .claude/skills/go-guide/ .claude/.archive/skills/
# ... (all unused)

# Move unused framework skills
mv .claude/skills/django/ .claude/.archive/skills/
mv .claude/skills/fastapi/ .claude/.archive/skills/
# ... (all unused)

2.3 Delete Strategy (Minimal Footprint)

For maximum reduction, delete unused guides entirely:

bash
# Delete unused language guide skills
rm -rf .claude/skills/python-guide/
rm -rf .claude/skills/go-guide/
# ... (all unused)

# Delete unused framework skills
rm -rf .claude/skills/django/
rm -rf .claude/skills/fastapi/
# ... (all unused)

Note: Deleted guides can be restored from the template repository if needed later.

2.4 Always Keep

Never remove these files regardless of stack:

  • .claude/README.md - Directory documentation
  • .claude/skills/README.md - Skills index (language guides, framework skills, custom skills)
  • .claude/skills/* - All skills (stack-agnostic utilities and workflows)

AI Action: Execute chosen strategy (archive or delete). Report space saved.

Step 3: Archive Stale Tasks

3.1 Identify Stale PRDs

Find PRDs and task files older than 6 months:

bash
# Find PRDs older than 180 days
find .claude/tasks -name "*" -mtime +180 -type f

3.2 Check Status

For each old PRD, determine status:

Status Action
Completed Archive to .claude/tasks/ARCHIVE/
Abandoned Archive with ABANDONED- prefix
Active Keep in place (update modified date)

3.3 Archive Process

bash
# Create archive directory
mkdir -p .claude/tasks/ARCHIVE

# Move completed/abandoned PRDs
mv .claude/tasks/0001-prd-old-feature.md .claude/tasks/ARCHIVE/
mv .claude/tasks/tasks-0001-prd-old-feature.md .claude/tasks/ARCHIVE/

# For abandoned, rename with prefix
mv .claude/tasks/0002-prd-never-built.md .claude/tasks/ARCHIVE/ABANDONED-0002-prd-never-built.md

AI Action: Identify stale tasks, confirm status with user, archive appropriately.

Step 4: Consolidate Memory

4.1 Identify Old Memory Files

Find memory files older than 3 months:

bash
# Find memory files older than 90 days
find .claude/memory -name "*" -mtime +90 -type f

4.2 Create Quarterly Summary

Consolidate old memory files into quarterly summaries:

markdown
# Q4 2024 Decision Summary

## Overview
This file consolidates decisions from October-December 2024.

## Key Decisions

### Authentication Strategy (2024-10-15)
- Chose JWT over sessions for stateless API
- See: archived/2024-10-15-auth-strategy.md

### Database Selection (2024-11-02)
- Selected PostgreSQL over MySQL
- See: archived/2024-11-02-database-choice.md

### Caching Approach (2024-12-10)
- Implemented Redis for distributed caching
- See: archived/2024-12-10-caching-approach.md

## Archived Files
- 2024-10-15-auth-strategy.md
- 2024-11-02-database-choice.md
- 2024-12-10-caching-approach.md

4.3 Archive Individual Files

bash
# Create archive directory
mkdir -p .claude/memory/archived

# Move old files
mv .claude/memory/2024-10-* .claude/memory/archived/
mv .claude/memory/2024-11-* .claude/memory/archived/
mv .claude/memory/2024-12-* .claude/memory/archived/

AI Action: Create quarterly summary, archive old memory files.

Step 5: Clean Patterns

5.1 Review patterns.md

If CLAUDE.md exists, review for:

  • Patterns referencing pruned languages/frameworks
  • Duplicate or similar patterns
  • Outdated patterns (superseded by newer approaches)

5.2 Remove Irrelevant Patterns

Example: If Python was pruned, remove Python-specific patterns:

markdown
## Removed Patterns

<!-- Remove this section if Python pruned -->
## Python Patterns
...

5.3 Consolidate Similar Patterns

Merge similar patterns across languages into generic versions where applicable.

AI Action: Review and clean patterns.md if it exists.

Step 6: Update Documentation

6.1 Update .claude/README.md

Add project-specific information:

markdown
# .claude/ Directory

> **Project**: MyApp
> **Stack**: TypeScript, React, Next.js
> **Last Cleaned**: 2025-01-15

## Active Guides
- Language: TypeScript
- Frameworks: React, Next.js

## Archived Content
See `.archive/` for pruned guides (can be restored if stack changes).

6.2 Update active-guides.json

Ensure manifest reflects final state after cleanup.

6.3 Add to .gitignore (Optional)

If not tracking generated content:

gitignore
# Optional: Don't track cleanup artifacts
.claude/active-guides.json
.claude/.archive/
.claude/memory/archived/
.claude/tasks/ARCHIVE/

AI Action: Update documentation to reflect cleaned state.

Output Summary

After cleanup, report:

## Cleanup Summary

### Space Reduction
- Before: 2.4 MB
- After: 156 KB
- Saved: 2.24 MB (93% reduction)

### Guides
- Language guide skills: 21 → 1 (20 archived)
- Framework skills: 33 → 2 (31 archived)

### Tasks
- Active PRDs: 3
- Archived PRDs: 5

### Memory
- Active decisions: 4
- Archived to quarterly: 12

### Files Updated
- .claude/README.md ✓
- .claude/active-guides.json ✓

Restoration

If you need a pruned guide later:

From Archive

bash
# Restore from archive
mv .claude/.archive/skills/python-guide/ .claude/skills/
mv .claude/.archive/skills/django/ .claude/skills/

From Template Repository

bash
# Re-download language guide skill from template
curl -o .claude/skills/python-guide/SKILL.md --create-dirs \
  https://raw.githubusercontent.com/ar4mirez/samuel/main/.claude/skills/python-guide/SKILL.md

# Re-download framework skill from template
curl -o .claude/skills/django/SKILL.md --create-dirs \
  https://raw.githubusercontent.com/ar4mirez/samuel/main/.claude/skills/django/SKILL.md

Update Manifest

After restoration, regenerate active-guides.json by re-running Step 1.

Automation (Future)

This workflow can be automated with a script:

bash
#!/bin/bash
# .claude/scripts/cleanup.sh

# Run cleanup workflow
# TODO: Implement automated detection and cleanup

Checklist

Before completing cleanup:

  • Active languages correctly identified
  • Active frameworks correctly identified
  • active-guides.json created
  • Unused guides archived/deleted
  • Stale tasks archived
  • Memory files consolidated
  • patterns.md cleaned (if exists)
  • README.md updated with project info
  • Space reduction reported
  • Git commit created (if desired)

Related Workflows

  • initialize-project.md - Run cleanup after initialization
  • troubleshooting.md - If cleanup causes issues
  • generate-agents-md.md - Regenerate AGENTS.md after cleanup

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results