/stow

name: stow
description: Sweep the current conversation for durable knowledge - user preferences, project facts, operational gotchas, standing decisions, and unfinished next steps - and file each through explicit instructions, existing local conventions, or the private `.stow-notes.md` fallback, curating tiered, decaying destination files as it writes. Use when the user invokes /stow, asks to save or write down what was learned this session, or before a context reset or long break.
user-invocable: true

<!-- maintainers: this is the public, installer-facing skill. Keep it standalone, with no private project paths, tool assumptions, or environment branching. The firstmate-internal counterpart lives at .agents/skills/stow/SKILL.md - deliberately a separate file with no shared code. Keep them independent. -->

stow

Sweep this conversation for durable knowledge that only exists in chat right now, and file it through the user's explicit instructions, the project's existing local conventions, or the private `.stow-notes.md` fallback in the current directory. The goal is to leave the next session a compact, current operating map, not an accumulating journal: every durable finding lands on disk, and every file this skill touches comes out more accurate, not merely longer. Entries are tiered and decay between passes, and stale material retires to a local archive instead of being deleted. Everything files to a local destination by default; an external system such as an issue tracker is reached only through the explicit-instruction rule in step 3.

What it does

1. **Sweep the conversation for uncaptured durable knowledge.** Read back over the session and look for:

• User preferences: a working-style, tooling, formatting, or approval preference the user stated in passing rather than through a config file.
• Project facts: build, test, deploy, architecture, or convention facts about the current project that would help anyone (or any agent) working in it later.
• Operational gotchas: a sharp edge, workaround, recurring mistake, or non-obvious cause discovered while working here.
• Standing decisions: a choice made this session that should outlive it, such as an approach settled on, an option ruled out, or a convention agreed to.
• Undone next steps: anything left open or agreed to that has not yet been written down anywhere.

Before filing any finding, check whether it already lives authoritatively somewhere - a README, a config file, existing docs, the code itself. If it does, record a one-line pointer to that owner instead of a copy, so the stowed note cannot go stale independently of its source.

2. **Discover the host's existing conventions before deciding where anything goes.** Don't assume a destination - look for what's actually there, roughly in this order:

• A project-level memory file, such as `CLAUDE.md`, `AGENTS.md`, or an equivalent at the repo root or nearby.
• A user-level (global) memory file the running agent reads across projects, if one exists and is readable.
• A `TODO`, `BACKLOG`, `NOTES`, or similarly named plain file already tracked in the project.

This step is about local files only; do not scan for or infer an issue tracker here - step 3 owns external routing.

3. **Route each finding using this fixed priority order, local-first.** 1. **Highest - an explicit instruction wins.** If the user has explicitly said, earlier in this conversation or as a standing choice previously recorded in the discovered user-level memory file (see step 4), to use a particular system for this kind of finding, route it there. This is the *only* path to an external or public system such as an issue tracker, hosted project board, or ticketing system. A configured git host remote, a `.github`/`.gitlab` folder, or any other signal that a tracker probably exists is never by itself grounds to file anything there - never route externally on inference. 2. **Otherwise - the local convention the project or user already has.** The discovered project memory file for project facts, operational gotchas, and standing decisions; an existing `TODO`/`BACKLOG`/`NOTES` file for undone next steps; a discovered user-level memory file for user preferences *when one happens to be accessible* - a bonus if reachable, never an assumption or a requirement. This is the only tier that writes findings into a tracked, shared file or outside the current directory, and only because the user already established that destination. 3. **Fallback - `.stow-notes.md` in the current directory, for every finding-kind.** When no existing convention fits, don't improvise a location or invent an ad hoc filename. In a git worktree, first verify `.stow-notes.md` is not already tracked in the index; if it is tracked, do not write private findings there - report that the fallback is blocked until the user chooses a safe destination. Otherwise create or update `.stow-notes.md` in the current working directory - never a user-level or home-directory path, so the fallback works even for agents sandboxed to the current directory. Then keep it out of git: add a `.stow-notes.md` line to a `.gitignore` file in the current directory - an ordinary file at that path, not git's internal exclude mechanism, which can resolve outside the working directory in a linked worktree. Leave staging or committing that `.gitignore` line to the user, same as everything else this skill writes. If even the `.gitignore` write fails, don't block or error - still write `.stow-notes.md` and tell the user to ignore it manually.

4. **When it's genuinely ambiguous between two existing conventions, ask once - then remember the answer.** If more than one discovered local convention plausibly fits a finding, ask the user once, plainly, which one they want that kind of note to live in going forward. The same applies when the user gives an explicit instruction to use a trac