Skip to main content
skill CX Codex

archive · rsmdt — Claude Code skill for archiving specs

Turns a finished specification into a compact file in .start/archive/ and removes its working folder. Run it after implementation to clear completed work from .start/specs/.

MIT ★ 587 updated 2026-10-26

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add rsmdt/the-startup
/plugin install start@the-startup
Open on GitHub

What archive does

The skill reads requirements and solution details from spec.md or the files in a legacy spec, then distills the intent, architecture, and key implementation references into .start/archive/[NNN]-[name].md. When it can identify the implementation commit in Git, it adds that reference. If the new spec replaces an earlier archived one, it links the records to each other.

Before deleting the working folder, the skill checks that the archive file exists and contains text. It then removes .start/specs/[NNN]-[name]/. Resolving the spec relies on specify-meta; if neither requirements nor solution can be found, it asks whether to remove the folder or stop. When there is no clear commit, it uses unknown rather than inventing a SHA.

What it helps with

  • condense a completed spec into one archive record
  • move finished work out of .start/specs/
  • keep a reference to the commit that shipped an implementation
  • link an archived spec to the one that replaces it

Example prompts for the agent

  • Run /archive 002 to archive the finished specification.
  • Archive the payment-processing spec after implementation.
  • Save the spec’s intent and architecture, then remove its working directory.

How to install archive

1Plugin marketplace

/plugin marketplace add rsmdt/the-startup
/plugin install start@the-startup

This installs the whole start plugin with all its skills

2Skills CLI (Vercel)

npx skills add rsmdt/the-startup --skill archive -a claude-code

3Manually: put the files in place

~/.claude/skills/archive/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/archive/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about archive

How do I install archive in Claude Code?

Add the marketplace with /plugin marketplace add rsmdt/the-startup, then install the plugin with /plugin install start@the-startup.

What does the archive skill do?

It creates a concise record of a spec’s intent, architecture, and implementation references in .start/archive/, checks the file, then deletes the matching directory from .start/specs/.

What if archive cannot identify the implementation commit?

It asks for a SHA or uses unknown when no clear commit can be found. It does not fabricate a commit reference.

Source text

SKILL.md · MIT
---
name: archive
description: Consolidate a completed specification into a single archived record and remove its working directory. Use as the final stage after implementation — distills requirements + solution into .start/archive/[NNN]-[name].md and deletes the .start/specs/[NNN]-[name]/ directory.
user-invocable: true
argument-hint: "spec ID to archive (e.g., 002), or spec name"
---

## Persona

Act as a specification archivist. When a spec's implementation is done, consolidate its intent and architecture into a single flat record under `.start/archive/`, then remove the working spec directory. The directory's disappearance from `.start/specs/` is the "done" signal — active work lives in `.start/specs/`, completed work lives in `.start/archive/` as one file per spec.

**Archive Target**: $ARGUMENTS

## Interface

ArchiveRecord {
  specId: string            // 3-digit, e.g., "002"
  specName: string          // e.g., "payment-processing"
  archivePath: string       // .start/archive/[NNN]-[name].md
  sourceDir: string         // .start/specs/[NNN]-[name]/ — removed on completion
  commit?: string           // short SHA + subject of the implementing/merge commit, or "unknown"
  supersedes?: string[]     // prior archived spec stems ([NNN]-[name]) this one replaces
}

State {
  target = $ARGUMENTS
  sourceDir: string
  requirements?: string     // spec.md (its Requirements part), or requirements.md in a legacy spec
  solution?: string         // spec.md (its Solution part), or solution.md in a legacy spec
  archivePath: string
  commit?: string           // resolved in step 3
  priorArchives?: string[]  // existing .start/archive/*.md scanned for supersession in step 4
}

## Constraints

**Always:**
- Resolve the spec via the specify-meta skill before reading anything.
- Read the spec document directly: the Requirements and Solution parts of spec.md, or requirements.md and solution.md (whichever exist) in a legacy spec.
- Write the archive record to `.start/archive/[NNN]-[name].md` BEFORE removing anything.
- Verify the archive record exists and is non-empty before removing the source directory.
- Remove the entire `.start/specs/[NNN]-[name]/` directory in a single step once the record is written.
- Keep the record short: high-level intent, architecture, and implementation references. Nothing else.
- Capture the implementing/merge commit (short SHA + subject) when the working tree is a git repo, so the record points back to the change that shipped it.
- Scan `.start/archive/` for prior records and, when this spec supersedes one, cross-link them bidirectionally (new record points back; superseded record points forward) before removing the source directory.
- Write the record yourself — do not spawn a subagent.

**Never:**
- Remove the source directory before the archive record is confirmed written and non-empty.
- Include user stories, Gherkin, EARS, acceptance criteria, or decision logs in the record.
- Restate requirements or solution verbatim — distill them.
- Pad the record with ceremony, narrative, or status fields.
- Require git, passing tests, or 100% completion — archive records what was done, in whatever state it is.
- Fabricate a commit SHA — record `unknown` when no clear commit can be determined.

## Reference Materials

This skill is intentionally self-contained; the record structure is inlined in step 5.

## Workflow

### 1. Resolve

Use the specify-meta skill with `$ARGUMENTS` to read the spec (`node ${CLAUDE_PLUGIN_ROOT}/scripts/spec.js {id} --read`). From the TOML output capture:
- `dir` → `sourceDir` (e.g., `.start/specs/002-payment-processing/`)
- the directory basename `[NNN]-[name]` → archive filename stem
- `prd` and `sdd` paths, if present (both are spec.md; a legacy spec reports requirements.md and solution.md)

```
match (resolution) {
  spec not found                         => report the error and stop
  neither requirements nor solution      => nothing to distill; ask the user whether to
                                            remove the directory anyway or abort
  at least one of requirements/solution  => proceed to step 2
}
```

### 2. Read Intent

Read the Requirements and Solution parts (spec.md, or the legacy requirements.md and solution.md, whichever exist). Extract only:
- **Intent** — what the feature is and why it exists (from requirements).
- **Architecture** — the components, how they fit, and any architecture diagram (from solution).
- **Implementation references** — the key modules/files and where they live (from solution).

Distill. Do not copy sections across; rewrite them to their high-level essence.

### 3. Identify the Implementing Commit

Find the commit that implemented or merged the feature so the record points back to the shipped change. Search history for the spec ID and name:

```bash
git log -n 5 --oneline --all --regexp-ignore-case --grep "{specId}" --grep "{specName}"
```

```
match (result) {
  not a git repo / git unavailable   => commit = "unknown" (do not fabricate)
  single clear match                 => commit = "{short-sha} — {subject}"
  multiple candidates                => present them; ask the user which one (or none)
  no match                           => ask the user for the SHA, or record "unknown"
}
```

### 4. Check Prior Archives for Supersession

List existing records in `.start/archive/` (skip if the directory does not exist yet). For each, judge whether this spec **affects or supersedes** it — same feature area, replaced architecture, or removed/renamed components.

```
match (relationship) {
  supersedes one or more   => record their stems in `supersedes`;
                              back-annotate each superseded record (step 5)
  related but not replacing => no cross-link (keep the record tight)
  none                     => no cross-link
}
```

When uncertain whether a prior spec is truly superseded, ask the user rather than guessing.

### 5. Write the Archive Record

Create `.start/archive/` if it does not exist. Write `.start/archive/[NNN]-[name].md`:

```markdown
# [NNN]-[name]

**Commit:** {short-sha} — {subject}   <!-- or: unknown -->
**Supersedes:** [NNN]-[name]   <!-- omit this line entirely when nothing is superseded -->

## What this is
{one or two plain sentences: the feature and its intent}

## Architecture
{the architecture diagram lifted from the Solution part, or a minimal one synthesized from
 its components; a short paragraph on how the pieces fit}

## Implementation
{key components/modules and where they live — the references for how it was built}
```

No frontmatter. No other sections. Keep it tight.

For each spec named in `supersedes`, back-annotate its existing archive record by inserting a line directly under its `# [NNN]-[name]` heading (do not otherwise alter it):

```markdown
**Superseded by:** [NNN]-[name]
```

### 6. Remove the Working Directory

Verify the archive record exists and is non-empty. Record the archive and keep the spec's event log beside its record:

```bash
node ${CLAUDE_PLUGIN_ROOT}/scripts/spec.js {specId} --event '{"kind":"archived"}'
mv {sourceDir}/events.jsonl .start/archive/[NNN]-[name].events.jsonl
```

Then remove the source directory in a single step:

```bash
rm -rf {sourceDir}
```

The scaffolding (`spec.md`, `review.md`, `.tracker/`, and in legacy specs `plan/`, `units/`, `scenarios/`, `manifest.md`, `README.md`) is removed with it — it all lives inside `sourceDir`.

### 7. Report

Confirm to the user:
- `Archived: [NNN]-[name] → .start/archive/[NNN]-[name].md`
- `Commit: {short-sha} — {subject}` (or `Commit: unknown`)
- `Supersedes: [NNN]-[name]` and `Updated: .start/archive/[NNN]-[name].md` (only when applicable)
- `Removed: {sourceDir}`

© Rudolf S. · MIT · rsmdt/the-startup

Similar skills

All skills for Agent setup: memory, context, orchestration →

archive by other authors comes first.

archive ReScienceLab Archives debugging solutions, deploy logs, and session takeaways into local markdown files. Keeps an indexed MEMORY.md file for cross-session agent reuse. CX Codex +1 1,200installs archive kirkchen Archives a completed Beat change: syncs capabilities into living documentation, moves the spec to archive, and hands off to the merge/PR step. Runs after /beat:verify and before the branch lands in main. CX Codex +1 524installs archive orwa-mahmoud Files completed Nightshift records into structured archive folders. Active project directories keep only open tasks and unresolved records. CX Codex +1 ★ 571repo stars unisecurityguard-academic-whistleblower-archive reason-machines unisecurityguard-academic-whistleblower-archive is a Claude Code skill that provides a GitHub repository template for documenting academic disputes and preserving social media posts before deletion. CX Codex +1 1,100installs javaBin archive — Norwegian Java community origins totto javaBin archive — Norwegian Java community origins is an MCP server for Claude Code with an archive of javaBin and JavaZone. It gives an agent sourced facts about the community, not guesses. CX Codex +1 annas-archive-ebooks ratacat annas-archive-ebooks searches and downloads ebooks from Anna's Archive by title or author in PDF, EPUB, or MOBI formats. Requires an archive membership. CX Codex +1 2installs pp-archive-is Matt Van Horn pp-archive-is finds cached pages, bypasses paywalls, and archives web pages with automatic fallback between backends. Helps agents read paywalled articles and batch-archive links. CX Codex +1 657installs platform-trust-archive-manage forcedotcom platform-trust-archive-manage — a skill for Salesforce Archive work through the Archive Connect API: search, unarchive, mask and erase archived records. CX Codex +1 5,200installs groove-utilities-task-archive andreadellacorte groove-utilities-task-archive archives completed and scrapped tasks in the configured backend. Use it when you want to close a batch of finished work with a confirmation step. CX Codex +1 533installs

From the same set50

The whole set →
validate validate orchestrates spec reviews, file audits, spec-to-code drift detection, and constitution rule checks across specialist subagents. CX Codex +1 ★ 587repo stars the-chief the-chief — a subagent that scores task complexity, maps dependencies, and routes work to maximize parallel execution. Use it when requirements are unclear, work spans multiple systems, or independent activities can run simultaneously. CX Codex ★ 587repo stars design-system design-system designs a service's architecture — pattern, data stores, scaling path — and hands back diagrams and ADRs. Useful when you're deciding whether to split a monolith. CX Codex ★ 587repo stars optimize-performance optimize-performance — a performance optimization subagent for Claude Code. Targets slow page loads, backend API latency, database queries, and memory leaks based on profiling metrics. CX Codex ★ 587repo stars implement An implementation orchestrator that reads slice and scenario tasks from the spec tracker, then launches a workflow which builds each slice and retries code→eval until holdout scenarios pass. CX Codex +1 ★ 587repo stars debug debug diagnoses software failures using a scientific method, strict hypothesis tracking, and root cause verification. CX Codex +1 ★ 587repo stars the-meta-agent The the-meta-agent subagent designs, audits, and refactors Claude Code subagents. Use it when an agent needs a focused scope, a clear workflow, or a specification check. CX Codex ★ 587repo stars improve improve finds modules with bloated interfaces and proposes refactors that turn them into deep ones — testable and easy for an agent to navigate. CX Codex +1 ★ 587repo stars

Project sponsors

Companies that keep this analytics open