# Maintenance Capsule

> Create, audit, refresh, or resume from a repository-local maintenance capsule: a goal-oriented standard project kernel that preserves identity, boundaries, acceptance evidence, stable baseline, and current handoff state across windows, models, people, and environments. Use when the user says 基因胶囊, 维护胶囊, 项目胶囊, 保存项目, 保存项目上下文, 保存当前项目状态, 固定项目, 固定项目风格, 固定当前项目状态, 项目封存, 项目交接, 换窗口继续, 接着做, 以后方便维护, 稳定风格, 维护升级, or asks to create or refine GOAL.md, optional repository AGENTS.md or HANDOFF.md, reduce bloated project rules, preserve a project for later continuation, or quickly recover where work stopped. Treat save, preserve, stabilize, handoff, and cross-window continuation requests as capsule requests by default; do not trigger on 固定 alone, ordinary code maintenance, a bug fix, or a one-off task with no continuity need.

- Skill: `xiaogege6697/maintenance-capsule` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add xiaogege6697/maintenance-capsule`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xiaogege6697/maintenance-capsule/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: xiaogege6697 (https://skillmd.com/u/xiaogege6697)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/xiaogege6697/maintenance-capsule

---


# Maintenance Capsule

Build the smallest repository-local project kernel that lets a fresh agent recover the project's identity, verify current reality, and continue from the right place without freezing the implementation.

Standardize what must be remembered, not how every project must be built. The capsule is a navigation and decision layer; the repository, Git state, tests, deployed behavior, and other current sources remain the operational truth.

## Choose a mode

- **init**: The repository has no capsule. Inspect it and create the minimum useful capsule.
- **audit**: A capsule or project instructions exist. Find duplication, stale facts, contradictions, and implementation-level overconstraint; remove what does not change decisions.
- **refresh**: The project goal, architecture, or stable baseline changed. Update the capsule to describe the new truth instead of appending history.
- **resume**: Work continues in a new window, model, person, or stage. Read the capsule, reconcile it with current reality, identify the current stage and next minimal action, then continue or report discrepancies before changing files.

Infer the mode from the request and repository. Do not ask when the evidence makes the choice clear.

## Inspect before writing

Read the real repository first:

1. Check Git status and preserve unrelated user changes.
2. Read existing repository instructions, README, primary entry points, tests, and deployment configuration.
3. Inspect current outputs or interfaces when user-visible correctness matters.
4. Identify the source of truth for facts that can drift.
5. Distinguish enduring intent from temporary state and implementation detail.

Do not create a capsule from the user's prompt alone when the repository can answer the question.

## Apply the narrow waist

Keep five cross-environment invariants:

1. **Goal**: What outcome must the project create, and for whom?
2. **Boundaries**: What truths, non-goals, safety limits, or identity must not be lost?
3. **Evidence**: What observable checks prove improvement or regression?
4. **Stable baseline**: What accepted artifact, version, or live target is the comparison or rollback point?
5. **Current handoff**: What stage is active, what is unfinished or unverified, and what is the next minimal action?

Leave implementation choices open unless a specific path is required for safety, compatibility, or deterministic correctness.

Do not confuse the stable baseline with work in progress. A baseline is accepted evidence; current handoff state may be incomplete, uncertain, or blocked.

## Create the minimum capsule

Default to one file:

```text
GOAL.md
```

Add only when earned by the project:

```text
AGENTS.md              # repository-local rules that change agent behavior
HANDOFF.md             # handoff state too large or volatile for GOAL.md
observable baseline    # evidence with real comparison value
```

### GOAL.md

Keep it concise and decision-bearing. Include:

- one-sentence project goal;
- 3–5 success criteria;
- the smallest set of narrow-waist boundaries;
- an upgrade method that changes one primary variable per iteration;
- project-specific acceptance evidence;
- the current stable baseline, if one exists;
- a short current handoff: stage, completed state, unfinished or unverified items, blockers, and next minimal action.

Treat `GOAL.md` as the project's identity card plus a short baton. Keep the handoff section compact and replace stale state instead of appending a diary. If it becomes longer than roughly 10–20 lines, changes much more frequently than project identity, or contains substantial temporary detail, move it to `HANDOFF.md` and leave a pointer in `GOAL.md`.

For comparisons, use **improved / unchanged / regressed + evidence**. Avoid numeric scores without a calibrated scale. Require critical identity and engineering quality not to regress, and require at least one evidenced improvement before release.

### AGENTS.md

Create or retain repository `AGENTS.md` only when local rules materially change decisions or protect the project. Host-wide rules alone are sufficient otherwise.

Keep repository instructions shorter than the goal document. When needed, it should:

- tell agents to read `GOAL.md` and inspect current reality first;
- protect source-of-truth and safety constraints;
- require scoped changes and real verification;
- preserve the user's commit, push, deployment, and destructive-action boundaries.

Point to `GOAL.md`; do not duplicate it. Prefer 4–7 rules.

### HANDOFF.md

Create `HANDOFF.md` only when the short baton no longer fits cleanly in `GOAL.md`. Keep only operational continuation state:

- current stage and last verified result;
- unfinished and explicitly unverified work;
- blockers or external dependencies;
- next minimal action;
- temporary safety warnings needed by the next agent.

Do not duplicate project identity, enduring boundaries, history, or general process rules. Replace resolved state and use Git or decision records for history.

### Observable baseline

Choose evidence by project type:

- UI: one approved screenshot or rendered artifact;
- API: contract tests and representative HTTP responses;
- CLI: golden commands and outputs;
- data pipeline: audit report or small golden dataset;
- library: public API tests;
- documentation: representative reader questions and expected answers.

Reuse verified artifacts when available. Do not manufacture a baseline merely to satisfy the structure. Add multiple baselines only when each protects a materially different risk.

## Audit by deletion

For every capsule statement, ask:

- Does it change a future decision?
- Is it enduring rather than temporary?
- Is it already enforced by code, tests, or Git?
- Does it duplicate another rule?
- Does it protect an outcome, or merely freeze an implementation?

Delete or merge statements that fail these tests. Do not add repository rules, directory blueprints, separate handoff files, changelogs, or process checklists by default. Add them only when project complexity creates a demonstrated decision, safety, verification, or recovery need.

When existing files would be semantically overwritten, present the intended diff before editing unless the user explicitly authorized direct execution.

## Refresh without accumulation

After a milestone:

1. Re-check the repository and external source of truth.
2. Replace stale current-state facts; do not preserve them as history in the capsule.
3. Update the baseline only after the new result is accepted.
4. Refresh the short handoff after a meaningful phase boundary; split or merge `HANDOFF.md` according to its current size and volatility.
5. Keep project history in Git, releases, or dedicated decision records—not in `GOAL.md` or `HANDOFF.md`.
6. Re-run the deletion audit and validation.

## Resume without archaeology

For resume mode:

1. Read `GOAL.md`, then optional repository `AGENTS.md` and `HANDOFF.md`.
2. Check the minimum real state needed to validate the handoff: Git status, relevant entry points, tests, outputs, or external source of truth.
3. State the recovered goal, active stage, discrepancies, and next minimal action.
4. If capsule and reality conflict, treat reality as evidence and pause before changing project identity, boundaries, or accepted baseline.
5. Continue under the existing acceptance standard; do not rebuild project context from scratch unless the capsule demonstrably fails.

## Completion check

Before handing off:

- verify a fresh agent can identify the goal, boundaries, evidence, stable baseline, current stage, and next minimal action;
- verify continuation does not require a full-repository archaeology pass or repeated background questions;
- confirm implementation freedom remains explicit;
- run relevant project validation;
- show the capsule diff and what was removed;
- do not commit, push, deploy, tag, or overwrite existing files beyond the user's authorization.