How to use the Project Graveyard agent skill

What an agent skill is and what this one does

An agent skill is a folder containing instructions (a SKILL.md file) and optionally scripts and reference notes that an AI agent loads when your request matches the skill's description. This one is aimed at finding and reviving dead projects.

When triggered, the skill scans folders for git repositories that have gone quiet, classifies each dead project by likely cause of death, such as being overtaken by a newer project or stalling at deployment, and summarises your recurring patterns. It then picks one project, checks whether the obstacle that stopped it has become easier since, and helps plan the steps to ship it. The bundled script is read-only and does not write inside any scanned repository.

Install the project-graveyard skill

Download the skill ZIP from this page and unzip it. You can install it in one of two ways.

For personal use across all projects, unzip it into ~/.claude/skills/. To limit it to one project, unzip it into that project's .claude/skills/ folder.

In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/project-graveyard/
• Single project: <your-project>/.claude/skills/project-graveyard/
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check the requirements before running

The skill needs Python 3.8 or newer and git available on the command line. It also needs access to the local folders you choose to scan. Web search is optional and only used for the world-check step, where the agent looks up whether the obstacle that stopped a project has since become easier to solve.

The skill runs a script and does not use the network for its analysis. Because the analysis relies entirely on git history, it will not help with folders that contain no git repositories.

• Python 3.8 or newer
• git on the command line
• Access to the folders you want scanned
• Optional: web search for the world-check

Trigger the skill with natural requests

You do not need a special command. Describe what you want in plain language. The skill's description covers requests about abandoned or unfinished side projects, questions like what you should finish, wanting to revive a project, wondering why you never finish anything, or starting a new project that resembles one you already built.

The skill also responds to the phrase run the graveyard. If you do not say where your projects live, the agent should ask you, rather than scanning your whole home directory.

• "What side projects should I finish?"
• "Run the graveyard on ~/dev and ~/projects."
• "Why do I never finish anything? Check my old repos."
• "I want to build a markdown note app. Did I already start one?"
• "Help me resurrect the most promising abandoned project."

Run the scan script directly and use its options

You can run the script yourself to see the raw report. Point it at the folders where your projects live. With no arguments it checks common locations such as ~/dev, ~/projects, ~/code and ~/Desktop.

• --days 90: how long a repo must be silent before it counts as dead (default 45)
• --json report.json: writes the full machine-readable data
• --me work@email.com: claims commits made under other email addresses; repeat the flag for more than one. Without it, projects committed under a work identity or a builder tool are skipped as not yours
• --include-foreign: also includes repos you barely committed to, such as clones, forks and work checkouts, which are skipped by default
• --state FILE: remembers scans and resurrections and enables relapse watch

Read the report and the cause-of-death labels

The report has four parts: a census, the dead projects with a cause of death, your patterns, and the top three by pulse, which is the resurrectability score. Each cause is an evidence-based guess rather than a verdict, and comes with the evidence line behind it. If a cause looks wrong, check the evidence before accepting it.

The agent may ask one or two questions about projects whose cause is unknown or a slow fade. Its answers are labelled as confirmed, while what git showed is labelled as forensic. The full cause taxonomy is in references/causes-of-death.md.

Safety notes: scripts, network and scanned folders

The skill runs a Python script, so read the SKILL.md and scripts/graveyard.py before running it if you want to check what it does. The script is read-only and never writes inside a scanned repository. The skill is designed to run locally, and the bundled script does not use the network.

Only point the scan at folders you are comfortable having read. Choose the folders explicitly instead of letting the scan sweep your home directory.

• The script does not delete anything.
• It does not write inside scanned repos.
• Use --redact framing if you want to share a report with project names replaced by project-1..n.