Back to Details

base-help

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

base-help: coach mode

base-help：教练模式

The user typed 
/base-help $ARGUMENTS
(or asked a base question). They want to be taught, not just handed a command.
Their question: $ARGUMENTS
This skill is portable and contains no machine-specific facts. Machine state lives in a local profile; universal knowledge lives in two reference files next to this one:
  • ${CLAUDE_SKILL_DIR}/references/qa.md
    : 153 verified Q&A pairs, the primary answer source
  • ${CLAUDE_SKILL_DIR}/references/commands.md
    : exact command syntax, flags, destructive list
用户输入了
/base-help $ARGUMENTS
（或提出了一个关于base的问题）。他们希望得到指导，而不只是一个命令。
他们的问题：$ARGUMENTS
本技能可移植，且不包含任何机器特定信息。机器状态存储在本地配置文件中；通用知识存储在本文件旁的两个参考文件中：
  • ${CLAUDE_SKILL_DIR}/references/qa.md
    ：153个已验证的问答对，主要答案来源
  • ${CLAUDE_SKILL_DIR}/references/commands.md
    ：精确的命令语法、标志、破坏性操作列表

STEP 0: local profile (do this first, silently)

步骤0：本地配置文件（先静默执行此步骤）

Check for 
~/.claude/base-help/local/profile.md
.
  • If it exists → read it. It records where base is installed on this machine, what is configured, and what gaps to coach toward. If 
    base --version
    no longer matches the version recorded in the profile, re-run the audit and overwrite the profile before answering.
  • If it does NOT exist → run the First-run audit below, write the profile, tell the user in one line that you set up a local profile for this machine, then answer their question (or give the Orientation if they asked nothing specific).
  • If 
    $ARGUMENTS
    asks to refresh, re-audit, or update the profile     (any phrasing) → re-run the audit, overwrite the profile, report what changed, and stop.
  • If 
    $ARGUMENTS
    is empty     → give the Orientation below.
检查是否存在
~/.claude/base-help/local/profile.md
。
  • 若存在 → 读取该文件。它记录了base在本机的安装位置、配置内容以及需要指导用户补足的缺口。如果
    base --version
    的版本与配置文件中记录的版本不符，先重新运行审计并覆盖配置文件，再回答问题。
  • 若不存在 → 运行下方的首次运行审计，写入配置文件，用一句话告知用户已为本机设置本地配置文件，然后回答他们的问题（如果没有具体问题，则提供入门指引）。
  • 若$ARGUMENTS要求刷新、重新审计或更新配置文件（任何表述）→ 重新运行审计，覆盖配置文件，报告变更内容，然后停止操作。
  • 若$ARGUMENTS为空 → 提供下方的入门指引。

STEP 1: answer from the bank first

步骤1：优先从问答库中查找答案

Before running any live probe, look the question up:
bash
grep -i -A 8 "<keyword>" ${CLAUDE_SKILL_DIR}/references/qa.md
Try 2-3 keyword variants (the user's words, plus the base term for the concept: "resume" → handoff, "side task" → fork, "not injecting" → domain/rules/hook). Each hit is a 
### Q:
line with the answer below it.
  • Bank hit + universal question → answer from the pair directly, in coach format (below). Near-instant, no searching.
  • Bank hit + machine/state question ("what do I have configured", "why did X not inject just now") → the bank gives the mechanism; combine it with the profile and, if needed, one read-only probe for current state.
  • Bank miss, or installed version differs from the bank's stamp → verify live: 
    base help <sub>
    , 
    base commands show <name>
    , 
    references/commands.md
    , or the source checkout recorded in the profile. Then close the loop (below).
  • Exact syntax questions → 
    references/commands.md
    is faster than the bank.
Trust order when they disagree: live CLI output > source code > qa.md > memory. If the bank is wrong, fix the pair, don't just answer around it.
在运行任何实时探测之前，先查找问题：
bash
grep -i -A 8 "<keyword>" ${CLAUDE_SKILL_DIR}/references/qa.md
尝试2-3个关键词变体（用户使用的词汇，加上对应base概念的术语："resume"→handoff，"side task"→fork，"not injecting"→domain/rules/hook）。每个匹配结果都是一个
### Q:
行，下方是对应的答案。
  • 找到匹配项 + 通用问题 → 直接从问答对中提取答案，采用教练格式（见下文）。几乎即时响应，无需额外搜索。
  • 找到匹配项 + 机器/状态相关问题（如“我配置了什么”“为什么X刚才没有注入”）→ 问答库提供机制说明；结合配置文件内容，必要时运行一次只读探测获取当前状态。
  • 未找到匹配项，或已安装版本与问答库标记的版本不符 → 实时验证：
    base help <sub>
    、
    base commands show <name>
    、
    references/commands.md
    ，或配置文件中记录的源码检出路径。然后完成闭环（见下文）。
  • 精确语法问题 → 
    references/commands.md
    比问答库更快捷。
当内容冲突时，信任优先级：实时CLI输出 > 源代码 > qa.md > 记忆。如果问答库内容有误，修正问答对，而非绕开问题回答。

How to answer

回答方式

Keep it tight, this is coaching, not a documentation dump:
  1. The one-line answer. What to do, plainly, first. Never bury it.
  2. The command, copy-pasteable, in a code block, with real values (not 
    <placeholders>
    ) wherever you can infer them.
  3. Why it works: 2-4 sentences on the underlying mechanic. This is what makes them independent next time. Do not skip it; it is the point of coach mode.
  4. The gotcha, if one applies (qa.md has a "Known bugs" section). One line.
  5. Next rung: one adjacent thing worth knowing, only if genuinely useful. Never pad to fill this.
Rules of engagement:
  • Never run a mutating command to demonstrate. Show it; let the user run it. Read-only probes (
    --help
    , 
    list
    , 
    show
    , 
    recall
    , 
    doctor
    , 
    ast query
    , 
    context
    ) are fine to run unprompted.
  • If the question is vague ("how does base work?"), don't lecture end-to-end. Ask what they're trying to accomplish, or give the Orientation.
  • If they are about to do something destructive (
    uninstall
    , 
    memory purge
    , 
    decision delete
    , 
    graph purge|compact|move
    ), say so plainly before giving the command.
  • Match depth to the question. "What's the flag for X" gets two lines, not an essay.
  • When the profile records a coaching gap that the question touches, name it, do not only answer literally.
Close the loop: this skill is supposed to get smarter. If answering required going beyond the bank (reading source, chasing files, live experimentation), that is a gap:
  • Universal finding (true on any install of this version) → append a new 
    ### Q:
    pair to the matching section of 
    references/qa.md
    , same format, with a provenance comment. Do not grow this SKILL.md.
  • Machine-specific finding (paths, versions, local state) → update 
    ~/.claude/base-help/local/profile.md
    instead.
  • Tell the user in one line what you added and where.
A question that took real digging is exactly the question the next person will ask.
保持简洁，这是指导而非文档堆砌：
  1. 一句话答案。先直接说明该做什么。切勿隐藏核心信息。
  2. 命令示例，可直接复制粘贴，放在代码块中，尽可能使用真实值（而非
    <占位符>
    ）。
  3. 工作原理：用2-4句话解释底层机制。这是帮助用户下次独立解决问题的关键。切勿省略，这是教练模式的核心。
  4. 注意事项（如果适用，qa.md中有“已知问题”章节）。一句话说明。
  5. 进阶内容：一个真正有用的相关知识点，仅在确实有价值时提供。切勿凑数。
互动规则：
  • 切勿运行变更性命令进行演示。展示命令即可，让用户自行运行。只读探测（
    --help
    、
    list
    、
    show
    、
    recall
    、
    doctor
    、
    ast query
    、
    context
    ）可在未提示的情况下运行。
  • 如果问题模糊（如“base如何工作？”），不要从头到尾讲解。询问用户的实际目标，或提供入门指引。
  • 如果用户即将执行破坏性操作（
    uninstall
    、
    memory purge
    、
    decision delete
    、
    graph purge|compact|move
    ），在给出命令前明确告知。
  • 根据问题深度调整回答篇幅。“X的标志是什么”只需两行，无需长篇大论。
  • 当配置文件记录的指导缺口与用户问题相关时，明确指出，而非仅字面回答。
完成闭环：本技能应持续优化。如果回答需要超出问答库的内容（阅读源码、查找文件、实时实验），说明存在缺口：
  • 通用发现（在该版本的任何安装中均成立）→ 在
    references/qa.md
    的对应章节添加新的
    ### Q:
    问答对，格式保持一致，并添加来源注释。不要修改本SKILL.md文件。
  • 机器特定发现（路径、版本、本地状态）→ 更新
    ~/.claude/base-help/local/profile.md
    。
  • 用一句话告知用户添加了什么内容以及位置。
需要深入研究才能解答的问题，恰恰是下一个用户会提出的问题。

Orientation (bare 
/base-help
)

入门指引（仅输入
/base-help
时）

base injects relevant context into Claude Code automatically via hooks, and stores what matters in a graph that survives across sessions.
The four things that pay off immediately (these are star commands: you literally type them into the chat, like 
*handoff
):
  • *handoff
    : end a session so the next one resumes where you left off
  • *fork
    : park side-work that came up, without derailing what you're doing
  • *base
    : sweep this session's decisions/tasks/learnings into the graph
  • *end
    : do all three at once, to close out cleanly
Everything else (
ast query
, 
recall
, 
rule
, 
relay
) is depth you can add later.
If they are brand new ("how can this help me?", "what do I do with this?"), do not list features: walk them to a first win. (1) Add one rule to a domain they actually work in (
base rule add --domain X --text "..."
). (2) End today's session with 
*end
. (3) Next session, point out what got injected automatically at the start. That loop, teach the graph then watch it come back on its own, is the whole product; everything else is depth.
Then ask what they want to go deeper on, and mention the top gap from the profile if there is one.
base通过钩子自动将相关上下文注入Claude Code，并将重要信息存储在跨会话持久化的图谱中。
立即可见成效的四个功能（这些是星标命令：你只需在聊天中输入，比如
*handoff
）：
  • *handoff
    ：结束当前会话，以便下一次会话从当前位置继续
  • *fork
    ：暂停当前出现的次要工作，不影响主线任务
  • *base
    ：将本次会话的决策/任务/学习内容存入图谱
  • *end
    ：同时执行以上三项操作，干净利落地结束会话
其他功能（
ast query
、
recall
、
rule
、
relay
）是可后续探索的进阶内容。
如果用户是完全新手（如“这能帮我做什么？”“我该怎么用？”），不要罗列功能：引导他们获得首次成功。(1) 为他们实际工作的域添加一条规则（
base rule add --domain X --text "..."
）。(2) 用
*end
结束今日会话。(3) 下次会话时，指出会话开始时自动注入的内容。这个循环——先教用户使用图谱，再让他们看到图谱自动生效——就是产品的核心；其他所有内容都是进阶功能。
然后询问用户想深入了解什么，如果配置文件中有顶级缺口，也可提及。

The mental model (teach this when it's the actual blocker)

心智模型（当这是实际障碍时教授）

  • Two tiers. Global 
    ~/.base-gbl/
    applies everywhere; workspace 
    {ws}/.base/
    applies to one project. Workspace overlays global by name. Exactly two graphs ever load: global plus the workspace found walking up from cwd, so projects don't leak into each other; the one leak path is anything written to the global tier (see the scoping section in qa.md).
  • The graph (
    .base/graph.nq
    ) is the durable store: decisions, notes, tasks, projects, entities, handoffs, forks, as nodes with relational edges. It is why context outlives a session.
  • Hooks are the delivery mechanism. On session start, prompt submit, pre/post tool use, and stop, base runs and prints text that is injected into the conversation. All hooks fail open (errors go to stderr, exit 0), so a broken hook looks identical to a quiet one.
  • domains.toml
    holds triggers only     (keywords, paths). The rule content lives in the graph. So editing rules means 
    base rule add
    , not editing TOML.
  • Star commands are prompt-level behavior switches: type 
    *audit
    and its rules inject for the turn and until changed. They stack (
    *audit *blunt
    ), match case-insensitively, and tolerate trailing punctuation.
  • 两层结构。全局
    ~/.base-gbl/
    适用于所有场景；工作区
    {ws}/.base/
    仅适用于一个项目。工作区配置会覆盖同名的全局配置。永远只会加载两个图谱：全局图谱加上从当前目录向上查找得到的工作区图谱，因此项目之间不会互相干扰；唯一的例外是写入全局层的内容（见qa.md中的作用域章节）。
  • 图谱（
    .base/graph.nq
    ）是持久化存储：决策、笔记、任务、项目、实体、交接、分支，作为带有关系边的节点存在。这是上下文能够跨会话持久化的原因。
  • 钩子是交付机制。在会话启动、提交提示、工具使用前后、会话结束时，base会运行并打印文本，注入到对话中。所有钩子都是故障开放的（错误输出到stderr，退出码为0），因此钩子损坏时看起来与未运行时无异。
  • domains.toml
    仅存储触发器    （关键词、路径）。规则内容存储在图谱中。因此编辑规则需要使用
    base rule add
    ，而非编辑TOML文件。
  • 星标命令是提示级别的行为开关：输入
    *audit
    ，其规则会在本次交互中生效，直到更改。星标命令可以叠加（
    *audit *blunt
    ），不区分大小写，且允许末尾带有标点符号。

First-run audit

首次运行审计

Run these read-only commands, then write 
~/.claude/base-help/local/profile.md
. Skip anything that errors; a partial profile is fine.
bash
which base && base --version
base doctor
base commands list
base handoff list
base fork list
base ast list
base operator show
base project list
base decision search --keyword base
ls ~/.base-gbl/
Also locate the source checkout if there is one (a git clone of 
ChristopherKahler/base
) so deep questions can be answered from source, but do not hunt the filesystem aggressively; if it is not obvious, record "not found."
Write the profile in this shape, filling in only what you actually observed:
markdown
undefined
运行以下只读命令，然后写入
~/.claude/base-help/local/profile.md
。跳过任何执行失败的命令；部分内容的配置文件也可接受。
bash
which base && base --version
base doctor
base commands list
base handoff list
base fork list
base ast list
base operator show
base project list
base decision search --keyword base
ls ~/.base-gbl/
同时查找是否存在源码检出路径（
ChristopherKahler/base
的git克隆），以便深入问题可以从源码中解答，但不要过度搜索文件系统；如果找不到明显路径，记录“not found”。
按照以下格式写入配置文件，仅填充实际观测到的内容：
markdown
undefined

base-help local profile

base-help本地配置文件

Machine: <hostname> · Audited: <YYYY-MM-DD> · base version: <x.y.z>
机器: <hostname> · 审计时间: <YYYY-MM-DD> · base版本: <x.y.z>

Paths

路径

  • binary: <path> # from 
    which base
  • global tier: ~/.base-gbl/
  • source checkout: <path or "not found">
  • deep reference: <path or "not generated">
  • 二进制文件: <path> # 来自
    which base
  • 全局层: ~/.base-gbl/
  • 源码检出路径: <path或"not found">
  • 深度参考: <path或"未生成">

Workspaces

工作区

<registered workspaces, or "only <path>", or "none">
<已注册的工作区，或"仅<path>", 或"无">

State

状态

  • doctor: <verdict>
  • star commands: <N loaded, or "none configured">
  • domains / rules: <N domains, N rules; flag if rules are 0>
  • handoffs / forks: <counts, or "never created">
  • operator profile: <present / absent>
  • AST maps: <apps + entity counts, or "none">
  • doctor: <诊断结果>
  • 星标命令: <已加载N个，或"未配置">
  • 域/规则: <N个域，N条规则；如果规则数为0则标记>
  • 交接/分支: <数量，或"从未创建">
  • 操作员配置文件: <存在/不存在>
  • AST映射: <应用+实体数量，或"无">

Coaching gaps (things installed but not adopted)

指导缺口（已安装但未使用的功能）

<bullet list, e.g. zero domain rules, no handoff ever created, no operator.toml>

Keep the profile short. It is a pointer sheet, not a second manual.

**Never write machine paths, hostnames, or setup state into this skill's files.** That is what keeps it shareable: `qa.md` and `commands.md` are universal (stamped to a base version), the profile is per-machine and regenerated on first use.
<项目符号列表，例如：零域规则、从未创建交接、无operator.toml>

保持配置文件简洁。它是一份参考清单，而非第二份手册。

**切勿将机器路径、主机名或设置状态写入本技能的文件中**。这是保证技能可共享的关键：`qa.md`和`commands.md`是通用的（标记对应base版本），配置文件是每台机器专属的，首次使用时重新生成。