如 my-expert，是专家的唯一标识。
如 design-expert → agents/design-expert.md。
如 ["./agents/my-expert.md"]，每个都要真实存在。
多于 3 必须替换或删除；第一条 quickPrompt = defaultInitPrompt。
突出核心能力，别写太长。
工具权限由系统统一分配。
如 trading-team-lead.md，不能用通用 team-lead.md。
teamInfo.memberAgents 不含 主理人。
两者中文必须完全一致。
同一团队头像画风、色调一致。
目录已有时，仍要走 validate → register。
每个专家必须完整经过 init → validate → register，禁止跳过。
.workbuddy-plugin/plugin.json，但 WorkBuddy 实际识别的目录是 .codebuddy-plugin/（本机 30+ 官方包全部如此）。照抄前者，专家根本不会被加载。
| 网传说法 | 正确做法 |
|---|---|
目录叫 .workbuddy-plugin/ | .codebuddy-plugin/ |
| tags / quickPrompts 随便加 | 必须恰好 3 个 |
主理人叫 team-lead.md | 带团队前缀，如 xxx-team-lead.md |
| 头像随便放 | 必须在 avatars/，团队风格统一 |
| 报错 | 原因 / 修法 |
|---|---|
| must have exactly 3 tags / quickPrompts | 数量不是 3，删到或补到 3 个 |
| members must contain a member with role='lead' | members 数组漏了主理人 |
| teamInfo.memberAgents should NOT contain the lead | 把主理人从 memberAgents 移除 |
| settings.json 'agent' != plugin.json 'agentName' | 让两者完全一致 |
| agentName has no matching file agents/xxx.md | 文件名与 agentName 对不上 |
| frontmatter must NOT contain 'tools' | 删掉 Agent MD 里的 tools 字段 |
| 专家不在专家目录下，将无法被检测到 | 必须放在 my-experts/plugins/ 下 |
「帮我写篇 2000 字 AI 工具盘点，读者 30+ 职场女性，轻松有梗，带 3 个案例」远比「写个推文」出活好。
改句话、改错别字别动整个团；复杂内容包才值得调专家团。简单任务用单专家更省。
每个任务开新对话，上下文干净，不会把无关内容算进 tokens。
广场里已有对口团，先召唤试跑，别重复造轮子。
分类、改写等轻活用轻量模型，把重模型留给真正复杂的分析。
新团先用小任务校准，跑顺再上完整内容包，避免积分打水漂。
来自社区与官方更新日志的真实踩坑，每日自动补充。
旧版存在「专家深链在冷启动期间无法打开专家详情」的问题，5.3.12 已修复。若你的专家/专家团分享链接偶尔打不开，先确认客户端版本；本教程创建的本地专家不受此影响。