l-auto-memory

Files (1)

• SKILL.md

SKILL.md (first lines)

# l-auto-memory

Every project carries what an agent needs to work in it, maintained
automatically as you work; don't wait to be told. Two parts:

- `skills/<name>/SKILL.md`: one skill per project-specific workflow.
- `AGENTS.md` at the root: the standing facts plus an index of those
  skills, so every agent session loads the index into context and opens
  the skill a task needs.

Three stores, three jobs, never mixed:

- `specs/` (`l-spec-driven-development`): what the system does and how it
  is built.
- `skills/` and `AGENTS.md` (this skill): how to work on and with the
  project.
- `tasks/context/` (`l-agent-task-db`): the findings and decisions of one
  ticket.

A convention learned while working a ticket goes into a skill or
`AGENTS.md`; the reasoning for that ticket's design stays in
`tasks/context/`. Personal preferences and cross-project habits stay in
the per-user memory, never in the repo.

## Project skills

A project skill explains one core workflow the way a teammate would show
it: the exact commands, in order, and what to check after each. Typical
ones:

- Using the project: running it, its CLI or API, its main use cases.
- Developing on it: build, test, debug, profile, release, the edit-run
  loop, adding a module or a plugin.
- Tools: how this project uses a specific tool (a simulator, a fuzzer, a
  deploy target, a database console).
- Access: how to reach a service, a server, a dashboard, and where its
  credentials live (the `pass` entry, the `secrets/` path, the env var
  name). Never the credential itself.

Layout and format:

- `skills/<name>/SKILL.md`, `<name>` lowercase kebab-case, named for the
  workflow (`run-tests`, `release`, `access-staging`). Supporting scripts
  sit next to it in the same directory.
- Frontmatter `name:` equal to the directory and a one-line
  `description:` saying what it covers and when to load it; the index
  copies that line.
- Symlink `.claude/skills -> ../skills`, so Claude Code discovers the
  skills natively; other harnesses reach them through the index.
  arch-dotfiles is the exception: its `l-*` skills are global, linked by
  `skills/mod.nu`, with no `.claude/skills` symlink, and its AGENTS.md
  indexes only the repo's own operational skills (the global `l-*` skills
  are indexed by the harness skill listing).
- One workflow per skill. A skill that grows a second workflow splits.

## AGENTS.md

`AGENTS.md` is read by opencode, Codex, Hermes and Claude Code (which
loads it wherever a directory has no `CLAUDE.md`), so there is no
`CLAUDE.md` beside it. If the repo already uses only `CLAUDE.md`, edit
that instead. One source of truth either way.

It holds:

- The skills index, first:
  ```
  ## Skills

  Load the skill a task needs from `skills/<name>/SKILL.md`.

  | skill | use it for |
  |---|---|
  | `run-tests` | running the suites, reading a failing seed, coverage |
  | `access-staging` | reaching staging, where its credentials live |
  ```
- Build/test/lint/run commands that work, the one-liners only;
  anything longer is a skill. The one line that matters most here is the
  pass/fail check the agent closes its own loop on (test, build, lint):
  with it the agent edits, runs, reads the failure and fixes without you;
  without it you are its test suite.
- Layout: where the important things live.
- Conventions: naming, error handling, commit style, branch model,
  `Merge policy:` and `Reviewer:` (`l-spec-driven-development`).
  Reference an in-repo guide rather than copying it.
- Gotchas: setup steps, env vars, flaky areas, things that look wrong but
  aren't.
- Links to `specs/INDEX.md` and any task db.

## When to write

- Starting in a repo with no `AGENTS.md`: create it, `skills/` and the `.claude/skills` symlink from what you
  discover: the real commands (from CI and manifests, not guesses), the
  layout, the stack.
- You performed a workflow that took more than one obvious command, or
  that cost you time to work out: write or update its skill and the index
  row.
- You found how to reach something, or where its credentials are: an
  access skill.
- A convention or command changed: update the stale skill or line in
  the same commit as the change; never append a contradiction.
- The user states a project rule ("we always X here"): record it. If the rule is project-specific, it goes in this repo's `AGENTS.md` or a skill; if it is a general, cross-project rule the user stated explicitly (a style, architecture or workflow habit), send it to the arch-dotfiles session to fold into the global `l-*` skills, so every project inherits it, and still note the project-specific slice here.

## What stays out

- Secrets and credential values. Locations only.
- Personal preferences and cross-project habits.
- Anything generated or already in the README or specs: link it.
- Anything the agent derives by reading the repo: file layout,
  conventions, the test framework, existing patterns. It reads the code
  faster than a description of it. Write down only what the code can't
  tell it: an off-repo decision, a command, a thing that looks wrong but
  isn't.
- Task state and completed-work logs.
- Speculation. Only record what you verified in this repo.

## How to keep it good

- `AGENTS.md` is read into context every session, so it stays small: a
  screen or two, declarative, no narration. Context is finite with

From lsck0/arch-dotfiles, MIT.

More from lsck0/arch-dotfiles