Chapter 12 · Built-in Skills: /ahoy, /bearings, /afk, /stow, /updatefirstmate

Chapter goals: Master FirstMate's five built-in user-invocable skills — session recap, fleet summary, away mode, knowledge stow, and self-update — and learn to combine them in日常运营.

12.1 Skill Invocation Overview

FirstMate ships with five built-in skills面向 the captain. The invocation prefix varies by harness:

# Claude Code and Grok use the slash form
> /ahoy
> /bearings file include PRs

# Codex uses the $ prefix, same names
> $afk
> $stow

The five skills'分工 summarized:

Skill	One-sentence定位
/ahoy	Recap what happened + guide you through unresolved items
/bearings	Generate a four-section fleet status summary
/afk	Auto-on-call mode while you're away
/stow	Stow persistent knowledge from the conversation to disk
/updatefirstmate	Safely self-update to the latest version

All five skills are stored as SKILL.md files in the .agents/skills/ directory (afk, ahoy, bearings, stow, updatefirstmate), loaded and executed by the firstmate at the corresponding trigger points.

12.2 /ahoy: First Thing Back at the Helm

When you return to the terminal and want to know "what happened while I was gone, what needs my decision," type /ahoy. It does three things:

1. RECAP    Review visible session events since the last real captain message
2. DECISIONS List visible but unanswered captain decisions
3. GUIDE    Guide decisions one at a time, ordered by the agent's judgment of impact

The third step is尤其贴心: instead of dumping a list of questions on you, it引导 one at a time — you answer one before moving to the next.

/ahoy has a special branch: if it is the first real captain message of this session (e.g., you typed /ahoy right after starting), it退化 to calling Bearings to生成 a summary, because there are no events since "the last message" to review.

12.3 /bearings: Four-Section Fleet Summary

/bearings generates a concise four-section chat summary from the local fleet state and registered secondmate status. It is a纯 read-only operation, ideal for快速了解全局.

It supports two composable variants:

# Base form: chat-only summary
> /bearings

# Variant 1: with real-time PR enrichment (still chat-only)
> /bearings include PRs

# Variant 2: write to today's report file and link in the summary
> /bearings file

# Combined: write file + PR enrichment
> /bearings file include PRs

When using the file variant, the report is重建 as a date-stamped file:

data/
└── status-report-2026-08-23.md   # data/status-report-<YYYY-MM-DD>.md

The underlying supporting script is bin/fm-bearings-snapshot.sh — it projects a structured fleet snapshot into a compact bearings view, local-only by default; only with explicit --include-prs does it发起 external PR enrichment requests. There is also an interactive upgrade /bearings lavish fleet panel, built and armed by bin/fm-bearings-board.sh.

12.4 /afk: Away Mode Auto-On-Call

/afk is the skill closest to "autopilot." When you need to step away from the keyboard (Away From Keyboard), activate it and the firstmate switches to a tiered on-call形态:

Responsibilities during /afk runtime:

Routine notifications ──► sub-supervisor handles via bash (does not disturb you)
Captain-related events ──► batched into digests for上报
Delivery wedges ──► proactive alarm (配合 wedge-alarm active reminder)

Three关键行为:

1. Sub-supervisor self-handling: routine notifications are消化 directly by the bash-layer sub-supervisor — no attention cost, no token cost;
2. Batched reporting:真正 captain-related events are not轰炸ed one-by-one; they are batched and presented as a digest;
3. Wedge alarm: if a delivery is stuck without progress, the system主动 upgrades an alarm — this is the user-side entry for the wedge handling logic in Chapter 11's watcher. The alarm channel is configurable via config/wedge-alarm, defaulting to macOS Notification Center (if available).

配套 scripts form a complete lifecycle: bin/fm-afk-launch.sh handles entering and rolling back, bin/fm-afk-start.sh provides the foreground daemon entry, bin/fm-afk-return.sh handles the deterministic return — closing on-call mode, organizing catch-up evidence, and setting a gate if there are阻塞 items the firstmate must处理.

12.5 /stow and /updatefirstmate

/stow: Conversation Knowledge Stow

Long conversations accumulate persistent knowledge that exists only in the chat history: your casually-stated工作 preferences, project facts, lessons learned, decisions made, next steps unfinished. /stow负责把这些清扫落盘:

/stow扫出的知识类别：
- 船长偏好（工作风格、沟通方式）
- 项目事实（架构决策、技术栈、重要约定）
- 踩坑记录（已解决的错误模式）
- 未完成的下一步（待 captain 确认的行动项）

Stowed知识写入 data/captain/learnings.md，下次会话启动时自动加载——这意味着你的偏好和决策不会被"聊完就忘"。

/updatefirstmate: Safe Self-Update

/updatefirstmate performs a安全 self-update to the latest distro version:

更新流程：
1. 拉取最新代码（git pull origin main）
2. 运行迁移脚本（如有）
3. 验证 AGENTS.md 兼容性
4. 重启 harness 加载新契约

关键安全设计：更新前会先做兼容性检查——如果新版 AGENTS.md 有breaking changes，firstmate会提示你review而不是直接应用。这确保了"自我更新"不会悄悄破坏你定制的运营契约。

12.6 Chapter Summary

• Five built-in skills: /ahoy (recap), /bearings (summary), /afk (away mode), /stow (knowledge stow), /updatefirstmate (self-update);
• /ahoy guides decisions one at a time;退化 to Bearings on first message;
• /bearings supports PR enrichment and file output variants;
• /afk switches to tiered on-call: bash handles routine, batches captain events, alarms on wedges;
• /stow persistently saves conversation knowledge to disk; /updatefirstmate safely self-updates with compatibility checks.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. What does /ahoy do when it is the first captain message of a session?

2. What is the key difference between /bearings and /bearings file include PRs?

3. What happens to routine notifications during /afk mode?

4. What safety mechanism does /updatefirstmate have before applying a new version?

🛠️ Hands-On Exercises

1. Start a session, dispatch a few tasks, then type /ahoy; observe the recap and guided decision flow.
2. Run /bearings file include PRs on a project with active PRs; verify the report file is created and PR data is enriched.
3. Activate /afk, dispatch a task that will take a while, step away, then return and type /ahoy; observe the batched digest vs. real-time notifications.

Built-in skills mastered. Next, two-layer skill system and custom extensions.