Ryuu's Skills

session-brief

Tells a new session its delivery mode, its branch, its plan row and the recent trail.

skills hook session-start runs on SessionStart and injects a short brief as additional context. It needs Bun. This is what survives a cleared context. In OpenCode the plugin runs it on a session's first model request and adds the brief to the system prompt of every request in that session. The lines, in order:

  • Delivery: prs, with greptile. The delivery mode and active reviewer extensions. Notes, such as an unreadable skills.conf, follow in parentheses.
  • An update notice, at most one, when there is something to say about updates:
    • Skills v1.2.0 is out: <url>. Run skills update., Skills updated v1.1.0 -> v1.2.0: <url>. or Skills update refused: <reason>.. Each shows once, on the first session start after the background run that found it.
    • Auto-update is not set. Run ./install.sh to choose. while AUTO_UPDATE is unset, at most once a day.
  • Branch: feat/x (3 changed, 1 untracked). The current branch and the counts from git status, where changed counts every entry, untracked ones included.
  • Machine: Studio Mac. This machine's label from its facts, once the plans store holds any. When the facts are missing or more than 24 hours old, the brief also starts skills machine refresh in the background.
  • Plan 090 docs-agents-hooks [DOING] .... The project's plan row whose branch column matches the current branch, when there is one. Branches carry no plan id, so that column is the link. A DOING row whose newest heartbeat or start is more than 30 minutes old is stale and ends in (<label>, stale <n> min), naming the machine holding its lease, or the machine that wrote that heartbeat or start.
  • /Users/you/Plans/Skills: 4 open. Run /plans for the frontier. The count of TODO, DOING, BLOCKED and REVIEW rows.
  • Inbox: 2 open, run skills issues list Skills. The count of open issues in the project's inbox, a number filed more than once counted as one, shown only when there is one.
  • Recent trail: and the last three trail lines for this project that name the plan or the branch.
  • device MacBook added by Studio Mac. With HUB_URL set and a plans.db, one line per membership chain entry this machine had not seen, as vault founded by <label>, device <label> added by <label>, device <label> revoked by <label> or epoch <n> started by <label>, shown only when the hook's short hub sync finishes in time.

The brief reads the rows and the trail from the store, plans.db, never from index.tsv or log.tsv. On a plans directory with no store yet, it runs the first import itself. When the store cannot open, or that import refuses, one line naming the plans directory and the reason takes the place of the plan lines, ending in fix it, then run skills plans import for a refusal.

The hook also records the session itself. When the host's payload names a session id and its working directory belongs to a project, it adds a session event to the store carrying the host, the session id, the branch, the plans whose row holds that branch, the start source and the time, and no path. Under a project transcript policy of off it records none. Sessions covers what happens to it next.

Updates

With AUTO_UPDATE at notify or on (see Configuration), a session start that finds no run started in the last 24 hours starts skills update --check, or skills update under on, in the background and returns without waiting on it. The run records its result in skills-update.json in the skills directory (AGENTS_DIR, by default ~/.agents/skills), and the next session start shows it as the notice above. The 24 hours count from the start, so a run that never finishes still holds the next one for a day. off, CI set, SKILLS_AUTO_UPDATE=0 or AGENT_HOOKS=0 start nothing and show no notice.

Claude Code and Codex also show the notice to you as the hook's systemMessage. OpenCode carries it in the brief only.

The CLI reads skills.conf and detects the project itself, through its shared delivery and project modules. Plans are read from PLANS_DIR, described in Configuration.

When It Stays Silent

The delivery line is always printed. After it, the lines up to the trail stop at the first thing the brief cannot find, and errors are swallowed. The hub lines still follow whatever was printed:

  • Outside a git repository, or on a detached HEAD, only an update notice and the hub lines follow the delivery line.
  • A git status slower than two seconds counts as no repository.
  • Without a plans directory or a matching project, no plan, count, inbox or trail line follows the branch and machine lines.
  • With no trail lines for this plan or branch, there is no trail.

With AGENT_HOOKS=0 set, nothing is printed at all.

On this page