name: agent-guild
description: |
智能体协会（agent-guild）— cross-agent shared memory. 本机多个 AI agent 共享
同一份身份、规则、记忆与交接消息 — 纯本地 Markdown/JSON，无服务器。

触发（任何自然等价表达都算）：
· 身份/习惯："我是谁" "我的身份/习惯/偏好" "who am I" "my routine"
· 回忆/历史："你记得吗" "之前聊过" "上次我们" "what did we discuss"
· 写记忆："帮我记住" "记一下" "沉淀一下" "remember this" "记到日志"
· 跨 agent："告诉其他 agent" "交接给" "让 XX 也知道" "hand off to"
· 当前状态："现在在做什么" "当前任务/焦点/进度" "current focus"
· 加入："加入协会" "初始化协会" "join agent guild" "install this skill"

能力：读/写共享身份、规则、焦点；收件箱交接；每日日志；跨 agent 学习台账
（错误/纠正/特性请求 → 复发追踪 → 晋升规则或萃取共享 skill）；`ag init/adopt/ bootstrap/doctor/upgrade/learn/review/resolve`（upgrade 自动从 skillhub/github/
clawhub 查最新版并更新）。
未加入？先跑 docs/ONBOARDING.md。
slug: agent-guild
displayName: 智能体协会 Agent Guild
protocol_version: "3.1"
version: "3.5.0"
license: MIT
homepage: https://github.com/dqsjqian/agent-guild
repository: https://github.com/dqsjqian/agent-guild
agent_created: true

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)

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.
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 当前焦点 → 你的未读收件箱。

文件	内容
`identity/profile.md`	用户是谁
`identity/ROUTINE.md`	日程 / 习惯
`rules/universal.md`	最高优先级戒律
`projects/active.md`	用户当前在做什么
`handoff/shared-state/current-focus.md`	各 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 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

File	Purpose
`~/.agent-guild/identity/profile.md`	Who the user is
`~/.agent-guild/identity/ROUTINE.md`	Daily schedule / routines
`~/.agent-guild/rules/universal.md`	Mandatory commandments — highest priority
`~/.agent-guild/rules/public-repo.md`	Public-repo hard rules
`~/.agent-guild/rules/file-cleanup.md`	File deletion preferences
`~/.agent-guild/rules/safety.md`	Safety guardrails
`~/.agent-guild/projects/active.md`	What the user is working on
`~/.agent-guild/handoff/shared-state/current-focus.md`	What any agent is focused on now
`~/.agent-guild/toolchain/*.md`	Tool-specific config — read on demand

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

Path	What goes there
`~/.agent-guild/memory/<agent>/`	该 agent 的私有记忆文件（`ag adopt` 搬进来后软链回原位，runtime 照常读写）
`~/.agent-guild/memory/shared/`	跨 agent 都该知道的事实（用户偏好、项目约定、踩过的坑）

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

Capability 8 — Learning ledger (self-improvement loop)

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

触发速查：

情况	动作
命令失败/异常/超时	`ag learn <agent> error "<summary>"`
用户纠正你（"不对"/"其实是"/"you're wrong"）	`ag learn <agent> learning "<summary>"`（category correction）
你的知识过时 / API 行为和认知不符	同上（knowledge_gap）
发现更好做法	同上（best_practice）
用户想要不存在的能力	`ag learn <agent> featreq "<summary>"`

复发追踪：相同 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 更新。

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

Agent Guild

Review

Why we picked it

What it does

Who it’s for

Risks & caveats

Review, then install

Repository facts

What this plugin covers

GitHub topics

Declared platforms

SKILL snapshot

Agent Guild — Runtime Skill

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

Mandatory Session Contract (once per session, MUST)

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

M1 — Bootstrap: read shared context BEFORE real work

M2 — Write memory after substantive work

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

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

Self-check (each session, before real work)

The `ag` CLI — use it for all writes

Capability 1 — Read shared user context

Capability 2 — Update current-focus

Capability 3 — Check inbox / send messages

Capability 4 — Daily log

Capability 5 — Refresh last_seen

Capability 6 — Where to persist shared data

Capability 7 — Cross-agent memory

Capability 8 — Learning ledger (self-improvement loop)

Failure modes

Spec

Pick By Human

@dshwork/config-dashboard

DSH-Plan-Graph

dsh-crew

Agent Guild

Review

Why we picked it

What it does

Who it’s for

Risks & caveats

Review, then install

Repository facts

What this plugin covers

GitHub topics

Declared platforms

SKILL snapshot

Agent Guild — Runtime Skill

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

Mandatory Session Contract (once per session, MUST)

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

M1 — Bootstrap: read shared context BEFORE real work

M2 — Write memory after substantive work

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

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

Self-check (each session, before real work)

The ag CLI — use it for all writes

Capability 1 — Read shared user context

Capability 2 — Update current-focus

Capability 3 — Check inbox / send messages

Capability 4 — Daily log

Capability 5 — Refresh last_seen

Capability 6 — Where to persist shared data

Capability 7 — Cross-agent memory

Capability 8 — Learning ledger (self-improvement loop)

Failure modes

Spec

Pick By Human

@dshwork/config-dashboard

DSH-Plan-Graph

dsh-crew

The `ag` CLI — use it for all writes