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
/plugin marketplace add rsmdt/the-startup
/plugin install start@the-startupWhat 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 002to archive the finished specification. - Archive the
payment-processingspec 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-startupThis installs the whole start plugin with all its skills
2Skills CLI (Vercel)
npx skills add rsmdt/the-startup --skill archive -a claude-code3Manually: put the files in place
~/.claude/skills/archive/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/archive/
1Skills CLI (Vercel)
npx skills add rsmdt/the-startup --skill archive -a codex2Manually: put the files in place
.agents/skills/archive/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add rsmdt/the-startup --skill archive -a cursor2Manually: put the files in place
.cursor/skills/archive/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install rsmdt/the-startup plugins/start/skills/archive2Manually: put the files in place
.github/skills/archive/SKILL.md1Skills CLI (Vercel)
npx skills add rsmdt/the-startup --skill archive -a gemini-cli2Platform CLI
gemini skills install https://github.com/rsmdt/the-startup --path plugins/start/skills/archiveManually: put the files in place
.devin/skills/archive/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.