Best for
- Use when the captain invokes /stow (e.
kunchenguid/firstmate/.agents/skills/stow/SKILL.md
Sweep the current session for uncaptured durable knowledge, file it to disk, persist the open work records this session knows are unfiled or now wrong, and curate the home's tiered, decaying startup memory before a context reset. Use when the captain invokes /stow (e.g. "/stow", "stow what you've learned"), before a session reset or context compaction, or periodically to keep operational memory current.
Decision brief
Sweep this session for durable knowledge and open-work record state that exist only in conversation, then leave the next session with a compact current operating map rather than an accumulating journal. Memory entries are tiered and decay between passes, and stale material retir…
Compatibility matrix
| Platform | Status | Evidence | What to check |
|---|---|---|---|
| Codex | Not declared | No explicit evidence | Portability before use |
| Claude Code | Not declared | No explicit evidence | Portability before use |
| Cursor | Not declared | No explicit evidence | Portability before use |
| Gemini CLI | Not declared | No explicit evidence | Portability before use |
Installation
The source command is displayed only when detected. A safe inspection prompt is always available so your agent can explain every action before execution.
npx skills add https://github.com/kunchenguid/firstmate --skill ".agents/skills/stow"Inspect the Agent Skill "stow" from https://github.com/kunchenguid/firstmate/blob/038d0f7ec6ba7238a151722931434dcf06ff37c4/.agents/skills/stow/SKILL.md at commit 038d0f7ec6ba7238a151722931434dcf06ff37c4. List every install step, command, network request, credential, file read/write, external action, and rollback step. Explain whether it fits my task. Do not install or execute anything until I approve.
Workflow
Markers are compact trailing HTML comments, deliberately cheap because marker bytes are counted content:
The wall-clock horizons above are this skill's default contract, and a home gets exactly them unless it asks for more. A home may opt in to a second, per-pass horizon by creating the local, gitignored config/stow-pass-horizon presence flag. While that file is absent nothing else…
Every /stow invocation performs this complete pass, even when the session contains no new finding:
Stale never means deleted: pruning an entry from an editable memory file always means moving it to data/memory-archive.md, this home's append-only, never-injected cold tier, gitignored with the rest of data/ and never counted by the budget report. Each archived entry keeps its p…
Reasons include unreinforced d, unreinforced p, budget oldest-first, and legacy-unvalidated. Archiving is a move, not a removal, and recovery is grep plus copy back with no tooling. Each home keeps its own archive, the archive never cascades, and truncating a grown archive is a…
Permission review
The documentation asks the agent to read local files, directories, or repositories.
Inspect each editable file's header pointer on every pass and add or correct it; for a read-only `data/captain-shared.md`, leave the file byte-identical and route a missing or outdated pointer to the primary owner.The documentation asks the agent to read local files, directories, or repositories.
Read every current memory file completely: `data/captain.md`, `data/captain-shared.md`, and `data/learnings.md`.The documentation asks the agent to create, modify, or delete local files.
For a pinned candidate, append a `proposed-offload` section with the same fields to the completion receipt and create or refresh one durable captain-held backlog item using `tasks-axi add`, `tasks-axi hold`, `tasks-axi show <id> --full`, anThe documentation asks the agent to create, modify, or delete local files.
For task-scoped notes, inspect the item with `tasks-axi show <id> --full`, classify the change as new, duplicate, superseding, or obsolete, then use a considered replacement body through `tasks-axi update <id> --body-file <path>`.Evidence record
| Signal | Value | Evidence type | Meaning |
|---|---|---|---|
| Quality score | 91/100 | Computed | Documentation, specificity, maintenance, and trust rules |
| Repository stars | 4,070 | Source | Repository attention, not individual Skill quality |
| Compatibility | 0 platforms | Source | Declared in the catalog source record |
| Usage guide | automated source guide | Editorial | Generated or reviewed according to the visible evidence level |
Pinned source
Sweep this session for durable knowledge and open-work record state that exist only in conversation, then leave the next session with a compact current operating map rather than an accumulating journal. Memory entries are tiered and decay between passes, and stale material retires to a cold archive instead of being deleted. This skill writes only through the existing Firstmate ownership and write boundaries.
Markers are compact trailing HTML comments, deliberately cheap because marker bytes are counted content:
<!--a:YYYY-MM-DD--> - an aging entry; the embedded date is its last-reinforced date.<!--p:YYYY-MM-DD--> - a perishable entry; the embedded date is its last-reinforced date.<!--a:YYYY-MM-DD/N--> - only in a home that has opted in to the pass horizon below: either dated marker may carry /N, the number of passes that evaluated the entry without reinforcing it.
An absent /N means zero, so an entry the fleet keeps exercising costs no counter bytes at all, and a home that has not opted in never writes one.<!--P--> - an explicitly pinned entry in a file whose default tier is not pinned.<!--g--> - migration-only: an unconfirmed legacy entry that has consumed its one grace cycle, carrying no date because grace is not reinforcement.- Treehouse pool slots share one repo, so workers must create their task branch before editing. <!--a:2026-08-03-->
- While state/.afk exists, the away-daemon owns triage (until the afk-wake fix lands; tracked: afk-pi-wake-bypass-r1). <!--p:2026-07-20-->
- Never restart the shared no-mistakes daemon while runs are active. <!--P-->
- Codex writes its trust prompt to stderr, not stdout. <!--a:2026-07-28/6-->
The tier names say what the pass does with an entry:
pinned - no clock is ever read for it: exempt from decay and from budget eviction, changed only through inspect-then-update when the captain or reality changes it, except that an explicit per-item captain approval may offload it under the flow below.aging - it must re-prove itself: an entry whose age is greater than or equal to 30 days since its last-reinforced date is stale, and a stale entry is re-validated (date refreshed) or archived, never kept by inertia alone.perishable - it is stored expecting disposal: an entry whose age is greater than or equal to 7 days since its last-reinforced date is stale, and its prose must name a checkable expiry condition, such as a backlog id, a version floor, or a dated expectation.
An admitted durable entry that cannot name a checkable expiry condition is not perishable and must be stored as aging.
Omission is reserved for non-durable material or facts already owned elsewhere.Marking rules:
data/captain.md and data/captain-shared.md default to pinned because preferences and authority boundaries do not age, and entries in data/learnings.md default to aging because operational facts must re-prove themselves.pinned default carries no marker at all; every aging and perishable entry always carries its dated marker, whose letter names the tier, so a clock-carrying entry is never ambiguous with unmarked legacy material.<!-- memory tiers: see the stow skill -->.
This skill text is the single owner of tier semantics, marker spellings, and clocks, and no memory file header may restate them.
The one exception is the config/stow-pass-horizon presence flag below, which turns a single extra horizon on for this home and changes nothing else on this page.data/captain-shared.md, leave the file byte-identical and route a missing or outdated pointer to the primary owner.
The required receipt action for that file is routed, not unchanged; name the ownership exception and do not declare the session reset-safe.Decay advances only when a pass runs, so a home stowed less often than a clock experiences that clock at its stow interval.
The wall-clock horizons above are this skill's default contract, and a home gets exactly them unless it asks for more.
A home may opt in to a second, per-pass horizon by creating the local, gitignored config/stow-pass-horizon presence flag.
While that file is absent nothing else in this section applies: no counter is written, no counter already in a file is read, and every entry decays on its date alone.
Opt in where admission and decay are not commensurable. A pass admits the findings that pass produced, so growth is a per-pass quantity, while a wall-clock horizon alone is a per-day one. In a home that stows daily those two rates diverge by the stow cadence, an entry the fleet keeps exercising never sits unreinforced for 30 wall-clock days, and the date horizon is evaluated vacuously every pass while the file only grows. A home stowed monthly already exceeds its date horizon on a single pass and gains nothing from the flag.
While the flag is present:
aging entry is stale at whichever horizon it reaches first: 10 passes that evaluated it without reinforcing it, or 30 days since its last-reinforced date.perishable entry is stale at whichever it reaches first: 3 unreinforced passes, or 7 days./N reads as counter zero, so a home that opts in migrates nothing./N already written is then neither read nor advanced, and is left in place rather than rewritten.Every /stow invocation performs this complete pass, even when the session contains no new finding:
bin/fm-startup-memory-budget.sh report before considering a write.
Record its effective budget and each file's estimated-token total.
The budget is per home: this home's three files against this home's own allowance, never a fleet total.
The helper's stable estimate is the documented conservative local approximation, not provider-exact accounting.
If it rejects the setting or a memory file, do not infer a default or silently continue.
Report that concrete exception and do not call the session reset-safe.data/captain.md, data/captain-shared.md, and data/learnings.md.
Treat an absent local file as absent, not as an invitation to manufacture content.
In a primary home, all three are curation inputs under their existing ownership rules.
In a secondmate home, data/captain-shared.md is a read-only primary-owned input: count it, never edit it, and curate only the editable local files.
Every mutation in the rest of this pass, including reinforcement, retiering, decay archival, legacy migration, consolidation, budget archival, and offload, applies only to an editable memory file.
When a read-only shared entry appears to require one of those changes, leave it untouched, report the required change as an ownership exception, and route it to the primary owner.data/learnings.md entry with no such evidence, the no-evidence path is always to append <!--g--> and retain it for this entire pass; never stamp or archive it during that same invocation.
Stamp each newly written entry with today's date and its tier per the marking rules, and admit a new perishable entry only with its named checkable expiry condition in the prose.aging entry from current evidence and refresh its date, or archive it.
Re-confirm a stale perishable entry against its named condition: still open means refresh the date, while resolved, expired, or no longer checkable means archive it in this pass.
Promote perishable to aging when its condition keeps proving durable past its expected life, and retier in place when a supersession changes an entry's lifetime.
pinned is exempt from this automatic decay step entirely.aging entries oldest-reinforced-first until within budget.
A proposal, a future migration, or an accepted exception is never budget relief in this pass.
Budget eviction considers only editable aging entries that carry a last-reinforced date and are not pending offload; a <!--g--> legacy-grace entry is ineligible until its grace cycle resolves, so eviction can neither cancel a promised grace cycle nor prefer just-validated entries over unvalidated ones.
Convergence precondition: before evicting anything, total the eligible pool and check that archiving all of it would reach the budget; when even that cannot, skip the eviction rung entirely, archive nothing for budget reasons, and carry the concrete inability to the final step, naming the exempt pinned floor that crowds out the budget.
Automatic processes never move a pinned entry: decay clocks, legacy grace cycles, oldest-first budget eviction, immediate budget archiving, and autonomous offload do not apply to it.
The sole exception is relocation to a JIT owner after explicit, per-item captain approval under the offload flow below, and that entry remains in memory until its destination is live.bin/fm-startup-memory-budget.sh report again after the complete pass.
Finish at or below the effective budget, or open a concrete captain decision before ending the pass.
A secondmate must explicitly report primary-owned-shared-file-alone-exceeds-budget when the inherited shared file alone exceeds its allowance, because local curation cannot resolve it.
Route that constraint to the primary owner and open one concrete captain decision at the primary owning level that names the shortfall, with exactly these options: raise the affected home's effective budget, or explicitly approve the primary owner trimming or offloading each named shared-file entry.
When the convergence precondition skipped eviction, report the exempt pinned floor and the remaining shortfall as that concrete inability rather than archiving eligible knowledge that could not close the gap.
Only after every safe non-pinned archival, consolidation, offload, and eligible eviction action is exhausted may a remaining excess be attributed to pinned safety, authority, or genuine captain-preference entries.
In that last-resort case, create one captain-held decision that names the shortfall and each relevant pinned entry, with exactly these options: raise the effective budget, or explicitly approve offloading or trimming a named pinned entry.
Route a read-only ownership constraint to its primary owner, and make every other unresolved excess a concrete captain decision that names the safe action still required.
Never end a pass over budget as an accepted exception.A net increase is allowed only for a genuinely new current fact with no stronger owner. Before allowing it, consolidate enough lower-priority material to remain within budget. Never describe the session as reset-safe while the memory total is over budget or an exception is unresolved.
Stale never means deleted: pruning an entry from an editable memory file always means moving it to data/memory-archive.md, this home's append-only, never-injected cold tier, gitignored with the rest of data/ and never counted by the budget report.
Each archived entry keeps its provenance under a dated pass heading: source file, tier, last-reinforced date, and the reason it left.
Include the unreinforced-pass counter only when the optional pass horizon itself made the entry stale, using the exact reason unreinforced <N>p; omit the counter when the wall-clock horizon or any other reason caused archival, even if the active marker carried one.
Archive provenance stays verbose rather than compact because the cold tier is never budget-counted.
## 2026-08-08 stow
- (from learnings.md, tier: perishable, reinforced: 2026-06-30) While state/.afk exists, the away-daemon owns triage... [archived: unreinforced 39d]
Reasons include unreinforced <N>d, unreinforced <N>p, budget oldest-first, and legacy-unvalidated.
Archiving is a move, not a removal, and recovery is grep plus copy back with no tooling.
Each home keeps its own archive, the archive never cascades, and truncating a grown archive is a captain decision, not a mechanism.
Decay handles staleness over time; offload handles scope: knowledge that is current and durable but relevant only in a nameable context, and therefore wrong to pay for in every session of every fleet member. For the offload sweep's evaluation only, each entry has exactly three outcomes decided in this fixed order:
The offload sweep runs whenever the pass is still over budget after decay archiving and consolidation, so routine passes do not move entries speculatively. It is an immediate reduction step for eligible non-pinned conditional material that can be added to an already-existing allowed owner, not a deferred proposal that leaves the pass over budget. Every test must hold for a candidate:
perishable, not stale, and expected to remain true for months.aging entry that is not pending offload may be autonomously relocated to an already-existing allowed owner, while a pinned entry may be proposed only for explicit, per-item captain-approved relocation and can never be archived or autonomously offloaded for budget relief.Hard rule: the stow process never creates or writes a firstmate-repo-tracked skill.
Every skill stow's offload produces for a Firstmate home is user-owned and local, excluded through that active home's repository-local exclude file resolved with git -C "$home_root" rev-parse --git-path info/exclude; contributing a lesson to the shared tracked template is a separate deliberate captain action, never automatic.
Approved project-level destinations are not produced by stow: they ship normally through that project's own registered delivery path.
.agents/skills/<freeform-name>/ whose path is appended to the active home clone's repository-local exclude file, never to a .gitignore.
Resolve home_root to $FM_HOME when it is set and otherwise to the Firstmate code root, and anchor every destination index check, exclude-path lookup, and ignore verification to that root with git -C "$home_root".
Before approval and again before migration, validate that the chosen freeform destination under home_root is absent from that home's git index and collides with no existing file or directory, and reject the destination if either check fails.
The name is freeform with no user-vs-firstmate naming convention, the skill stays per-home and untracked, and the harness still lists and JIT-loads it because skill discovery scans the filesystem and ignores git status (verified in docs/verification/stow-memory.md).
Its precise, condition-stated description line is its entire trigger; it gets no AGENTS.md declaration because AGENTS.md is shared tracked material.
Because this destination is local and untracked, it is also the JIT home for private conditional knowledge that no committed surface may hold.AGENTS.md, for project-intrinsic knowledge useful to nearly every session of that project, through a normal crewmate ship task using bin/fm-ensure-agents-md.sh and the project's registered delivery mode.Forbidden destinations: any firstmate-repo-tracked skill per the hard rule; firstmate's own AGENTS.md, which is always-loaded for every fleet session; docs/ alone, which is never agent-loaded on demand, though a skill body may point into docs for depth; and any committed surface for private content.
A local skill exists only in this home, so offloading an entry out of data/captain-shared.md removes it from every inheriting home's always-injected memory: the proposal must say so, and the default for shared entries is keep.
AGENTS.md, then confirming that destination holds the quoted entry before removing the memory entry.
A destination that needs creation, uncompleted project delivery, or any other future work is not live and cannot count as relief, so continue with the next archival or eviction rung instead of leaving an over-budget proposal pending.proposed-offload section with the same fields to the completion receipt and create or refresh one durable captain-held backlog item using tasks-axi add, tasks-axi hold, tasks-axi show <id> --full, and tasks-axi update <id> --body-file <path> as appropriate.
Preserve each candidate's approval state in that item, and require explicit plain-chat approval for that named item before any migration.
If the captain never answers, nothing migrates and the held item persists, but it is never treated as budget relief.home_root to $FM_HOME when it is set and otherwise to the Firstmate code root, then re-validate the approved local-skill destination under that root for both index absence with git -C "$home_root" and filesystem collision absence.
Before creating the destination or writing any private content, resolve the exclude file with git -C "$home_root" rev-parse --git-path info/exclude, append the destination directory path to it, and verify the future SKILL.md path is ignored with git -C "$home_root" check-ignore.
Only after that verification succeeds, create the destination and write the SKILL.md with its precise description trigger, then confirm the skill appears in a fresh session's skill index.
If any migration step fails, remove the destination content and the exclude rule written by this attempt, leaving neither partial private content nor a partial rule behind.
An approved project destination ships as a normal task through that project's registered delivery mode.
The migration's source of truth is the entry as quoted in the proposal.data/learnings.md only for a genuinely new local learning with no stronger owner.AGENTS.md.
Route it through a normal ship task so a crewmate records it with bin/fm-ensure-agents-md.sh and the project's delivery path.tasks-axi show <id> --full, classify the change as new, duplicate, superseding, or obsolete, then use a considered replacement body through tasks-axi update <id> --body-file <path>.
Use --archive-body when recoverability matters.
Never append.blocked-by dependency when applicable.data/memory-archive.md, autonomous offload of an eligible non-pinned conditional entry to an already-existing allowed owner through the reduce flow above, captain-approved offload of a pinned durable conditional entry to a JIT-loaded owner executed through the migration step above, or deletion of an entry that is a duplicate or already preserved through a stronger existing owner.
A stale unique fact is never deleted, only archived.
Do not invent another graduation path.The sweep above preserves knowledge; this one preserves the state of work. A reset destroys whatever exists only in this session, and that includes what you have learned about work already under way, not just facts worth remembering. So before the reset, make sure the important open work you are holding in context is durably recorded: file what was never filed, and correct what you now know is stale.
Judge for yourself what is important and which record each thing belongs to, and write it through the owner that already governs that record. One bound holds: this covers the open work you are actually holding in context, not the records at large. It is not a reconciliation of durable records against repository or forge reality, cannot become one on input this volatile, and must never be reported as one. Where the right correction is a judgment you cannot make, leave the record alone and raise the question instead of guessing.
Legacy entries carry no markers; an unmarked entry is its file's default tier with unknown age, and unknown age is not guilt. The first pass after adoption performs a one-time revalidation sweep of editable memory files instead of blanket restamping, while a read-only shared file remains untouched and any required change is routed to its primary owner:
data/captain.md and data/captain-shared.md, every unmarked entry is simply default-pinned and remains exempt from the aging clock, legacy grace cycle, and archive-by-age; consolidation still applies, and only genuine tier deviations receive markers.data/learnings.md, stamp each entry the pass can confirm current with its compact dated marker for today, using a deviating tier letter or <!--P--> only where the entry genuinely deviates from the aging default.data/learnings.md, add <!--g--> as its trailing marker and retain it through the rest of that pass; carrying no date, it persists that the entry has consumed exactly one grace cycle without pretending it was reinforced.<!--g--> when this invocation began is on the next-pass branch: replace that marker with the normal dated tier marker if independent current-session evidence confirms the entry; otherwise archive it with provenance legacy-unvalidated.data/learnings.md.Report the outcome in plain captain-facing language with all of these facts:
data/captain.md, data/captain-shared.md, and data/learnings.md, using only unchanged, added, rewritten, pruned, routed, archived, or proposed-offload; adding or replacing a migration marker is rewritten, never a new action verb such as migrated;proposed-offload section with every candidate's fields;State what reset-safe means in the same breath as the claim: nothing this session knew has been lost. It is never a claim that the home's durable records are correct, because this pass checks no record the session did not name. Do not hide an over-budget result behind a reset-safe claim. In a primary home the receipt is written after the cascade below, not instead of it.
In a primary home, every /stow cascades to every registered secondmate after this home's own required pass and knowledge sweep are complete.
In a secondmate home, /stow curates that home only and never cascades further.
The cascade changes nothing until /stow is invoked: it adds no notification, no digest section, and no background work.
Run bin/fm-stow-cascade.sh once the primary's own pass is done.
It enumerates each registered secondmate exactly once, reports that home's own budget accounting, and resolves how the sweep reaches it; its header owns the stanza fields, the bound, and the exit codes.
Every home is judged against its own config/startup-memory-budget allowance, so never add homes together or treat one home's excess as another's.
Act on each home by its reported transport:
agent - send the marked request with bin/fm-send.sh fm-<id> "<request>" so the live secondmate performs its own /stow, including the uncaptured knowledge that exists only in its session.
Ask it for the same completion receipt this skill defines, and read its reply from its status file or the document it points to, never from its chat.direct - curate that local home's editable memory files yourself under the same retention plan, then re-run the cascade to confirm the after totals.
data/captain-shared.md stays a read-only counted input there, exactly as it is in any secondmate home.deferred - a remote home with no live agent. Its memory is accounted read-only and cannot be curated from here, because there is no generic remote write path for a home's own memory files.
Report it as an unresolved exception and leave it to its next cascade.
Relaunching that secondmate is a separate decision owned by secondmate-provisioning, never something /stow does on its own.unavailable - that home's own accounting did not complete. Report the concrete exception and continue; a slow or unreachable home never blocks this home's /stow.A newly discovered shared captain preference still routes to the primary's data/captain-shared.md under the existing primary-authoritative contract, whichever home found it.
Offload proposals and the cold archive are per-home: file proposals only in the home whose pass produced them, and never cascade either to another home.
Extend the completion receipt with one entry per secondmate alongside the primary's own, carrying that home's budget before and after, its per-file actions, its exceptions, and whether that home swept itself or was curated from here. Keep those entries in the same plain captain-facing language the rest of the receipt uses. The session is reset-safe only when every home is within its own budget with no unresolved exception.
The stow pass itself must never store, create, or edit a skill as a destination for any finding.
The exclusion binds the pass as a writer: proposing an offload and letting the migration step execute a captain-approved candidate later is not the pass storing a skill.
Every Firstmate-home skill that migration produces is user-owned and local under the destinations hard rule, while an approved project-level destination is produced and shipped through that project's registered delivery path, never by stow.
Changing firstmate's tracked .agents/skills/ or public skills/ remains a deliberately scoped Firstmate repository task through its pipeline, never a stow product.
Outside a captain-approved offload, generalizable knowledge still routes to shared tracked material through its pipeline and fleet-local knowledge to data/.
Frequently asked questions
Sweep this session for durable knowledge and open-work record state that exist only in conversation, then leave the next session with a compact current operating map rather than an accumulating journal. Memory entries are tiered and decay between passes, and stale material retir…
The source record exposes this install command: npx skills add https://github.com/kunchenguid/firstmate --skill ".agents/skills/stow". Inspect the command and pinned source before running it.
Static rules flagged read-files, write-files in the source; the page lists the matching lines and excerpts.