Agent Guild

Agent Guild — Runtime Skill

Local-first cross-agent shared memory. Join once, share identity/rules/focus across every agent on this machine. Data lives at ~/.agent-guild/ (plaintext, yours, never uploaded).

SKILL_DIR below means the directory containing this file. CLI entry point: python3 <SKILL_DIR>/scripts/ag.py (referred to as ag). Requires Python 3.9+ (stdlib only, no third-party packages). On Windows use python instead of python3 if that is what your PATH exposes.

Quick start (for an agent that has NOT joined yet)

1. Run the onboarding flow: ~/.agent-guild/ONBOARDING.md (or this skill's docs/ONBOARDING.md) — discover your runtime's user-extensible skills dir, install this skill (symlink → copy → readonly), run the closed-loop trigger test, register yourself in registry.json.
2. Then come back here — this file is your everyday capability.

Mandatory Session Contract (once per session, MUST)

⛔ 这些是强制动作，不是建议。每次会话开始（或首次需要用户上下文时）执行，不要等用户点名。 全部通过 ag 一条命令完成，别手工开五个文件。

No shell / no Python? Every step below has a plain-file equivalent — read the listed files directly and Edit them in place. The contract still applies; only the mechanism changes. On Windows, use python if python3 is not on PATH.

M0 — Ensure the guild exists (first use / every session start)

python3 <SKILL_DIR>/scripts/ag.py init <your-agent-name>

幂等：目录不存在则建全套骨架 + 落地本 skill；已存在则只补缺失项，绝不覆盖已有数据。 输出 initialized = 首次自举，verified = 已存在。

M1 — Bootstrap: read shared context BEFORE real work

python3 <SKILL_DIR>/scripts/ag.py bootstrap <your-agent-name>

一次读全：用户画像 → 日程 → 最高优先级戒律 → 在做的项目 → 各 agent 当前焦点 → 你的未读收件箱。

读到什么就按什么做。没读就动手 = 违反协议。 之后按需再读 toolchain/*.md、其他 rules/*.md。

M2 — Write memory after substantive work

完成实质工作后 MUST 追加 daily log（见 Capability 4）。满足任一即"实质工作"： 产出交付物（代码/文档/报告/网站/脚本）・改了代码或配置・做了技术决策・修复错误并定位根因・学到可复用的长期事实（用户偏好/项目约定/坑）。

跳过：寒暄、简单查询、短问答、纯检索。

跨 agent 有价值的事实 → 也写 memory/shared/；只对你自己有意义的 → 留在 memory/<你的名字>/。

踩坑/被纠正/发现更好做法 → 同时记学习台账（Capability 8，ag learn）。 用户纠正了你・命令非预期失败・用户想要不存在的能力・发现某任务更优解 —— 这些是全 guild 的免疫素材，别只留在当天日志里。绝不记录 secrets/原始报文，摘录要脱敏。

M3 — Route skills & data into the guild (default-on)

• 装新 skill：MUST 装到 ~/.agent-guild/skills/<name>/，再从那里软链回自己 runtime（symlink → copy → readonly 降级，见 ONBOARDING.md Step 3）。
• 写持久化数据：MUST 写 ~/.agent-guild/skills_data/<skill>/（敏感数据拆 private/）。
• MCP / 插件 / CLI 工具：分别进 mcp/、plugins/、tools/。
• 唯一豁免：你的 runtime 强制私有路径（如 platform-managed）——在 registry 里记录原因即可，不算违反。

M4 — Self-audit: adopt what's still scattered (first join + monthly)

python3 <SKILL_DIR>/scripts/ag.py adopt <your-agent-name>            # DRY-RUN, 只报告
python3 <SKILL_DIR>/scripts/ag.py adopt <your-agent-name> --apply    # 真的搬 + 软链回来

扫五类资产：skills / skills_data / mcp / tools / memory。 默认 dry-run，先把清单给用户看；--apply 才动手（搬完自动验证软链，失败自动回滚，删除走废纸篓）。

自动排除：可重建缓存（.venv/node_modules/__pycache__）、凭证、runtime 内部元数据、平台托管包（__skillhub/connector-*）、connector 型 skill。

健康检查（发现悬空软链 / 旧路径残留 / registry 漂移）：

python3 <SKILL_DIR>/scripts/ag.py doctor

Self-check (each session, before real work)

# 1. registered?
grep -q '"<your-agent-name>"' ~/.agent-guild/registry.json && echo registered || echo not_registered
# 2. protocol version compatible?
grep -E '"protocol_version"' ~/.agent-guild/skills/agent-guild/manifest.json | head -1

Not registered → run onboarding first. Central major version > yours → re-run onboarding from the top.

The ag CLI — use it for all writes

Writes to shared files are atomic + audited when done through the CLI (zero-dependency Python, stdlib only). Reads stay plain file reads.

AG="python3 <SKILL_DIR>/scripts/ag.py"

$AG init <agent>                    # bootstrap the guild (idempotent)
$AG bootstrap <agent>               # read ALL shared context in one shot
$AG adopt <agent>                   # dry-run: what of mine belongs in the guild?
$AG adopt <agent> --apply           # move it in + symlink back
$AG doctor                          # dangling links / stale paths / drift
$AG status                          # who is registered
$AG register <agent> <home> <tier>  # join (tier: symlink|copy|readonly)
$AG last-seen <agent>               # refresh presence
echo "<body>" | $AG send <dst> <topic>        # handoff message
echo "<body>" | $AG log <agent> "<title>"     # daily log
echo "<body>" | $AG focus <agent> "<title>"   # update current-focus
echo "<body>" | $AG learn <agent> <kind> "<summary>"  # learning ledger entry
                                             #   kind: learning|error|featreq
                                             #   opts: --area X --priority Y --pattern-key K
$AG review                          # pending stats + promotion candidates
$AG resolve <ID> ["note"]           # mark entry resolved (+ note)
$AG groom [--dry-run]               # data hygiene: archive expired data
                                    #   (auto-runs after bootstrap, 1/day)
$AG audit                           # audit trail of shared writes
$AG prune 30                        # list idle agents

If the CLI is unavailable (no Python, sandboxed runtime), fall back to the manual file operations below — Edit in place, never Write-overwrite a shared file. Every capability in this skill is reachable by plain file reads/writes; the CLI only adds atomicity and an audit trail.

Capability 1 — Read shared user context

Read on demand; don't slurp everything every turn.

Capability 2 — Update current-focus

current-focus.md is the "what's hot right now" board. When you start or finish a major task, prepend your block (ag focus or manual Edit in place). Never rewrite history other agents wrote.

Capability 3 — Check inbox / send messages

Inbox: ~/.agent-guild/handoff/inbox/.

• Receive: ls ~/.agent-guild/handoff/inbox/ | grep "to-<your-agent-name>-", read, act, then mv to handoff/archive/.
• Send: from-<src>-to-<dst>-<topic>.md — write for a recipient with no context (what you did, what's left, where artifacts are).

Capability 4 — Daily log

After substantive work (built/fixed/decided/learned a lasting fact), append to ~/.agent-guild/log/daily/YYYY-MM-DD-<your-agent-name>.md — per-agent file, append-only. Skip greetings / lookups / short Q&A.

Good entry: ## <title> + What / Why / Result / Cross-agent note (if others need to know).

Capability 5 — Refresh last_seen

Once per session, update your entry's last_seen (prefer ag last-seen, fallback Edit). Never overwrite the whole registry — patch only your entry.

Capability 6 — Where to persist shared data

New skill / MCP / plugin / tool / persistent data you install → MUST go under ~/.agent-guild/{skills,skills_data,mcp,plugins,tools}/<name>/, not a private path (唯一豁免见 M3). The user backs up the whole ~/.agent-guild/ with one command.

Capability 7 — Cross-agent memory

写之前先读：别把别人已经记过的东西重复记一遍。

Capability 8 — Learning ledger (self-improvement loop)

三本跨 agent 台账在 ~/.agent-guild/learnings/：LEARNINGS.md（纠正/知识盲区/最佳实践）· ERRORS.md（命令/集成失败）· FEATURE_REQUESTS.md（用户想要但不存在的能力）。 完整规范（schema/触发词/晋升阈值/萃取流程）：docs/LEARNINGS.md（权威）。

触发速查：

复发追踪：相同 Pattern-Key 的条目跨 agent 计数；ag review 报告达到阈值的组。

晋升（达到阈值后 MUST，详见 docs/LEARNINGS.md）： 行为/偏好 → rules/<topic>.md；工具坑 → toolchain/<tool>.md 或 memory/shared/； 通用可复用解法 → 萃取为 skill 放 skills/<name>/（共享 skill bus，全 agent 即刻可用）， 条目状态改 promoted / promoted_to_skill。

红线：不记 secrets/token/原始报文；条目只增不改，仅 Status/Resolution 可由任何 agent 更新。

Capability 9 — Data hygiene (ag groom, protocol 3.2+)

协会用得越久，数据越容易劣化：current-focus 只增不减、daily log 无限堆积、 audit 越滚越大、resolved 台账条目永远躺在 live 文件里。groom 是自动防线：

• 自动触发：ag bootstrap 尾部挂钩（速率限制默认 24h 一次），skill 正常 触发即自动维护，无需用户点名。
• 保真原则：只搬不删 —— 过期数据进 log/archive/、 handoff/shared-state/archive/、learnings/archive/ 或可恢复的 .trash/； 手写的、无时间戳的 focus 块永远不动；未读收件箱永远只报告不搬。
• 策略可调：所有阈值在 ~/.agent-guild/RETENTION.md（用户文件，升级不覆盖）。
• 可审计：每次 groom 写 log/audit.jsonl + .groom.json 状态。

Failure modes

• Some files missing → read what exists, note the rest, don't block.
• registry.json not writable → log the issue, proceed read-only.
• Inbox file in an unexpected format → read anyway, reply with a structured request for clarity.

Spec

• Manifest: manifest.json
• Onboarding (one-time): docs/ONBOARDING.md
• Conventions: docs/CONVENTIONS.md
• Learning ledger (self-improvement): docs/LEARNINGS.md
• Repository: https://github.com/dqsjqian/agent-guild
• License: MIT