[jasontopia]

Intent

在 learn-firstmate 里加一份 firstmate 命令和技能的使用说明

What Changed

• Added references/commands-and-skills-guide-2026-10-15.md, a Chinese quick-reference for captains. It starts with a table that maps everyday needs to commands. It then covers each command a captain can type: /afk, /quiet, /ahoy, /bearings (including file, lavish, and include PRs), /stow, /updatefirstmate, and the harness-registered /calm and /supervision-model. For each one it says what the command does, when to use it, gives an example, and lists what it will not do on its own. It also lists the 6 user-invocable skills, the installable stow variant, and the firstmate-only reference skills. Every section cites its source files in the FirstMate repo.
• Linked the new guide from the references list in README.md.
• Extended GLOSSARY.md with supervision host and a new "命令与技能" table (skill, slash command, agent-only reference skill, digest, board, completion receipt, pinned), so the guide uses one fixed rendering for each term.

🤖 Generated with Claude Code

Risk Assessment

✅ Low: This is a documentation-only change, and its claims check out against the read-only FirstMate source: there are 6 user-invocable skills, the 23 agent-only skills are all listed, and the stow local-skill and pinned-entry wording matches the source; the round-2 glossary fix adds only the missing pinned term, in the table's existing format.

Testing

The baseline docs check (python3 scripts/check-docs.py) had already passed. This is a pure Markdown change to a tutorial repo with no build or runtime, so no product surface can be driven live. The scenarios that would exercise it are running FirstMate slash commands in a live agent session, which would need a real captain session in the read-only FirstMate checkout, so none were driven live. Read-only checks show the guide's skill tables match the FirstMate checkout exactly (6 user-invocable, 23 agent-only, firstmate-calm is a symlink), every cited source file exists, the recorded review fixes are present, and there are no em dashes. No visual artifact was captured: the deliverable is plain Markdown, and rendering it through GitHub's markdown API would publish the content to an external service.

• Live validation: ⚠️ no-surface - 0 of 4 scenarios driven live against the product

Scenario	Result	Live	Evidence
A reader opens README.md, follows the new 命令与技能使用说明 link and reaches the guide	⏸️ untested	no	Docs-only change with no runtime product surface. Link resolution is covered by the repo's own static docs check, which is not a live product run.
A captain types a command from the guide (/afk, /quiet, /ahoy, /bearings, /stow, /updatefirstmate, /calm, /supervision-model) in a FirstMate session and sees the behavior the guide describes	⏸️ untested	no	No live-validatable surface in this repo. This step would need a live FirstMate captain session backed by an LLM harness, inside the FirstMate checkout, which AGENTS.md says is read-only and must not…
A reader checks the guide's split between skills they can call and agent-only skills against the real FirstMate skill set	⏸️ untested	no	Docs-only change. The comparison is a read of the source files, not a product run, so it is not marked as live.
A reader looks up the new terms (技能, 斜杠命令, 大副专用技能, 摘要, 看板, 回执, 固定) in GLOSSARY.md and finds one rendering each, matching the guide	⏸️ untested	no	Docs-only change with no runtime surface. Checked by reading the files only.

Evidence: Skill classification check against the FirstMate checkout

user-invocable: true -> afk, ahoy, bearings, quiet, stow, updatefirstmate (6, matches guide table)
user-invocable: false -> 23 skills, matches the guide's agent-only tables (4+11+3+2+2+1)
firstmate-calm -> symlink to ../../.claude/mods/firstmate-calm, no SKILL.md (matches the guide's section 三)
all skills carry metadata.internal: true (matches the guide's claim)

- Outcome: ⚠️ 1 warning across 1 run (51.7s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 2 issues found → auto-fixed (2) ✅

• ⚠️ references/commands-and-skills-guide-2026-10-15.md:174 - The /stow section's bullet "不会自己写或改任何技能" is too broad, and the source contradicts it. .agents/skills/stow/SKILL.md (section 'Over-budget offload to JIT-loaded owners' > 'Destinations' and 'Flow: reduce, approve, migrate, remove') says what stow is forbidden to touch: a skill tracked in the FirstMate repo ('Hard rule: the stow process never creates or writes a firstmate-repo-tracked skill'). It does write user-owned local skills. When memory is over budget, it moves eligible non-pinned conditional entries into an already-existing local, untracked skill under .agents/skills/<freeform-name>/ without asking. After per-item captain approval, it moves pinned entries into a new local skill directory, which it creates and excludes from git. A captain reading the current wording would wrongly conclude stow never writes skill files. Suggested fix: say it never writes or changes skills tracked in the FirstMate repo, and that when over budget it may move entries into a local, untracked skill that exists only on this machine (pinned entries only with your per-item approval). This would also tie up the vague '迁出去' at line 160. The public skills/stow statement at line 262 ('它不会往技能里存东西') is accurate and needs no change.
• ℹ️ references/commands-and-skills-guide-2026-10-15.md:99 - The /ahoy description says "凡是 PR，都给完整的 https:// 链接", which overstates the source. .agents/skills/ahoy/SKILL.md step 4 only requires it to 'preserve every full PR URL present in that interval'. Step 6 forbids it from calling GitHub, running tools or reading files. So if a PR shows up in the conversation only as #123, /ahoy cannot produce a full link for it. Suggested wording: 对话里出现过的 PR 完整链接会原样保留.

🔧 Fix applied.
3 issues (1 warning, 2 infos) still open:

• ⚠️ references/commands-and-skills-guide-2026-10-15.md:174 - The /stow section's bullet "不会自己写或改任何技能" is too broad, and the source contradicts it. .agents/skills/stow/SKILL.md (section 'Over-budget offload to JIT-loaded owners' > 'Destinations' and 'Flow: reduce, approve, migrate, remove') says what stow is forbidden to touch: a skill tracked in the FirstMate repo ('Hard rule: the stow process never creates or writes a firstmate-repo-tracked skill'). It does write user-owned local skills. When memory is over budget, it moves eligible non-pinned conditional entries into an already-existing local, untracked skill under .agents/skills/<freeform-name>/ without asking. After per-item captain approval, it moves pinned entries into a new local skill directory, which it creates and excludes from git. A captain reading the current wording would wrongly conclude stow never writes skill files. Suggested fix: say it never writes or changes skills tracked in the FirstMate repo, and that when over budget it may move entries into a local, untracked skill that exists only on this machine (pinned entries only with your per-item approval). This would also tie up the vague '迁出去' at line 160. The public skills/stow statement at line 262 ('它不会往技能里存东西') is accurate and needs no change.
• ℹ️ references/commands-and-skills-guide-2026-10-15.md:99 - The /ahoy description says "凡是 PR，都给完整的 https:// 链接", which overstates the source. .agents/skills/ahoy/SKILL.md step 4 only requires it to 'preserve every full PR URL present in that interval'. Step 6 forbids it from calling GitHub, running tools or reading files. So if a PR shows up in the conversation only as #123, /ahoy cannot produce a full link for it. Suggested wording: 对话里出现过的 PR 完整链接会原样保留.
• ℹ️ references/commands-and-skills-guide-2026-10-15.md:174 - The guide coins the rendering 「固定」 for the memory-tier term pinned inline, but GLOSSARY.md has no entry for it. AGENTS.md says GLOSSARY.md 'is the only copy of the term table: add a new term there rather than coining a rendering inline'. This change already adds a 「命令与技能」 section to GLOSSARY.md (GLOSSARY.md:76-86), but pinned was left out. The round-1 fix moved the first bilingual use from line 176 to line 174, and line 176 now uses Chinese only, which is correct. The same term sits in the stow tier vocabulary, next to aging and perishable, which a later chapter or reference may need. Remedy: add | pinned | 固定 | to the 「命令与技能」 table in GLOSSARY.md. Nothing else in the guide needs to change.

🔧 Fix applied.
✅ Re-checked - no issues remain.

⚠️ **Test** - 1 warning

• ⚠️ this change has no live-validatable surface; proceed without live validation? (0 of 4 scenarios were driven live against the product); A reader opens README.md, follows the new 命令与技能使用说明 link and reaches the guide: Docs-only change with no runtime product surface. Link resolution is covered by the repo's own static docs check, which is not a live product run.; A captain types a command from the guide (/afk, /quiet, /ahoy, /bearings, /stow, /updatefirstmate, /calm, /supervision-model) in a FirstMate session and sees the behavior the guide describes: No live-validatable surface in this repo. This step would need a live FirstMate captain session backed by an LLM harness, inside the FirstMate checkout, which AGENTS.md says is read-only and must not have state-changing commands run in it. The change itself is only Markdown text.; A reader checks the guide's split between skills they can call and agent-only skills against the real FirstMate skill set: Docs-only change. The comparison is a read of the source files, not a product run, so it is not marked as live.; A reader looks up the new terms (技能, 斜杠命令, 大副专用技能, 摘要, 看板, 回执, 固定) in GLOSSARY.md and finds one rendering each, matching the guide: Docs-only change with no runtime surface. Checked by reading the files only.
• Live validation: ⚠️ no-surface - 0 of 4 scenarios driven live against the product

Scenario	Result	Live	Evidence
A reader opens README.md, follows the new 命令与技能使用说明 link and reaches the guide	⏸️ untested	no	Docs-only change with no runtime product surface. Link resolution is covered by the repo's own static docs check, which is not a live product run.
A captain types a command from the guide (/afk, /quiet, /ahoy, /bearings, /stow, /updatefirstmate, /calm, /supervision-model) in a FirstMate session and sees the behavior the guide describes	⏸️ untested	no	No live-validatable surface in this repo. This step would need a live FirstMate captain session backed by an LLM harness, inside the FirstMate checkout, which AGENTS.md says is read-only and must not…
A reader checks the guide's split between skills they can call and agent-only skills against the real FirstMate skill set	⏸️ untested	no	Docs-only change. The comparison is a read of the source files, not a product run, so it is not marked as live.
A reader looks up the new terms (技能, 斜杠命令, 大副专用技能, 摘要, 看板, 回执, 固定) in GLOSSARY.md and finds one rendering each, matching the guide	⏸️ untested	no	Docs-only change with no runtime surface. Checked by reading the files only.

• python3 scripts/check-docs.py
• python3 scripts/check-docs.py (baseline, already run by the pipeline: link integrity and formatting hygiene)
• git diff --stat 4cf0d06..a9bbd14 and reviewed the GLOSSARY.md and README.md diffs
• Read-only check of every .agents/skills/*/SKILL.md in the FirstMate checkout for user-invocable and metadata.internal, compared with the guide's 6-skill table and 23-skill agent-only tables
• Read-only ls confirming the cited sources exist: docs/calm.md, docs/configuration.md, docs/architecture.md, docs/supervision-host.md, bin/fm-afk-launch.sh, skills/stow/SKILL.md
• sed of the guide's /ahoy and /stow sections, checking the round-1 and round-2 fixes are in place
• grep -c '—' on all changed files (0 em dashes)

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.