Imported from ZhangXin8069/configure (skills/up/SKILL.md). Install upstream with npx skills add ZhangXin8069/configure --skill up. Copyright stays with the author.

up — agent 配置库升级技能

执行前置

遵循当前目录 AGENTS.md「技能执行公共契约」；仅按需读取技能正文与 reference。

把“agent 配置持续更新”固化为可重复流程：本地四类目录基线调查 → 多源最佳实践与热榜调研 （连接失败重试至成功）→ 差距分析 → 执行（优化/补充/新增/debug）→ 自我进化 → 验证 → 收敛评估 → 升级汇总。默认目标是当前 Git 仓库根目录下的 skills/、tools/、hooks/、 plugins/；目录缺失或为空只记录事实，不凭空创建内容。若存在 .opencode/skills/，它是 技能加载镜像，按双目录约定同步核对，不另行扩大主目标范围。借鉴来源必须写出网站、仓库或 技能名与 URL。

核心原则

1. 本地四树基线先行：先只读检查当前 Git 根目录下的 skills/、tools/、hooks/、 plugins/，掌握目录完整性、格式、接口和安全边界后再谈升级；不调查就升级是臆断。
2. 多源互证并启用热榜：代码托管源至少覆盖 GitHub、Gitee、GitLab，并可补充 Codeberg； 规范/实践源至少核对一个权威规范和一个社区实践。各源按自身 star 字段降序取榜，star 只 是发现候选的信号，不是质量结论；跨源合并时保留来源，不把不同站点的 star 当成同一标尺。
3. 网络调研重试至成功：连接、超时、DNS、TLS 或解码失败时沿 API → 网页 → 备用域名/ 延长超时路径持续重试，直至成功或用户终止；HTTP 4xx/不支持的接口切换回退并报告， 不把永久错误伪装成“正在重试”；每次失败记录 URL、错误类别和重试次数。
4. 差距分析证据驱动：逐条对照（四树现状 vs 最佳实践）形成差距表，只升级有实据的差距； 不编造“最佳实践”内容，借鉴内容注明来源网站、仓库和技能名。
5. 最小改动：优化只改差距所在处，遵循当前公共契约与既有格式；skills 改动遵循 SKILL.md + AGENTS.md + 技能表/镜像 约定，tools/hooks/plugins 只改其真实接口、清单或 安全缺口，不因目标扩展而批量重写。
6. 验证闭环：每处改动后验证结构、触发、脚本语法、可执行权限、清单一致性、热榜排序和 镜像同步等与改动直接相关的性质；没有刚运行的证据就不声明“通过”。
7. 收敛判定：全部差距处理完毕、连续两轮无实质变化、收益低于 5% 或用户终止时收敛； 收益微小时报告权衡，不无限扩大范围。
8. 受约束的自我进化：当目标包含 up 自身时，只把当前运行证据、可复现失败或用户明确 反馈提炼为通用规则；每轮最多落地一个有边界的候选，保留 frontmatter、四树范围、验证、 安全和不越权等不变量，禁止递归自改造成无限循环。
9. 内部联动更新（三查 + 双目录）：技能核心流程变化后检查调用链、互鉴表、技能表/计数和 .opencode/skills 镜像；外部升级与内部联动缺一不可，只引入不联动会留下断链。

Git 收尾

有 Git 且存在本次会话产生的文件改动时，先执行 git diff --check 和定向差异复查，只核对本次 文件，不使用 git add -A/git add .。用户明确授权提交时，再只暂存本次文件、执行 git diff --cached --check 并创建本地提交，不推送；未获授权时不暂存、不提交，只报告检查结果。 无 Git 或无本次改动时立即跳过。

触发时机

• 用户要求升级 agent 配置："升级技能库"、"更新 skill/tool/hook/plugin"、"整理 agent 配置"、 "up"；默认检查仓库根目录四树，用户明确缩小范围时按指定范围执行。
• 用户要求外部调研或热榜："引入 GitHub/Gitee/GitLab skill"、"参考社区最佳实践"、 "按 star 排名"、"搜热门 agent skill"、"查代码托管平台"。
• 用户要求检查/修补行为："skill 没触发"、"配置过时"、"工具或 hook 有问题"、"插件兼容性"。
• 用户要求插件推荐或一键安装脚本："添加更多推荐"、"提供安装脚本"、"一键安装插件"； 按原生 manifest、marketplace 入口、许可证和权限风险核对后再登记。
• 用户要求 up 自身进化："让 up 自我改进"、"吸收本次失败经验"、"up 自我进化"。
• 与其他技能配合：优化单个 skill 自身 → skill-creator；技能触发/行为异常 → debug； 纯性能问题 → optim；升级后查看改动 → diff；需要反复迭代至最佳 → all； 多目标树的独立基线/差距评估 → dispatch 并行派发；升级后打标签仅在用户明确要求时 → tag。

工作流程

Step 1. 解析升级目标

确认以下边界并输出一句任务定义：

1. 默认范围是 git rev-parse --show-toplevel 得到的根目录下 skills/、tools/、hooks/、 plugins/；用户明确指定子目录时只收窄，不越过仓库根目录。
2. 外部参考至少包含 GitHub、Gitee、GitLab 三个代码托管源；网络可达时补充 Codeberg， 再从 agentskills.io、Anthropic 官方技能仓库和 obra/superpowers 等规范/实践源核对。
3. 热榜默认开启：按任务主题生成同一查询词，每个可达代码托管源取前 N（默认 10）个结果， 按该源原生 star 字段降序；用户明确关闭时才不检索热榜。
4. 自我进化在目标包含 skills/up、用户明确要求 up 自改，或当前运行发现 up 规则缺口时启用； 其余任务不借机修改 up 自身。
5. 收敛标准为差距表清零或明确记录遗留项，并通过与改动对应的结构、行为和安全验证。

Step 2. 本地四树基线调查（只读）

REPO_ROOT="$(git rev-parse --show-toplevel)"
for rel in skills tools hooks plugins; do
  path="$REPO_ROOT/$rel"
  if [ -d "$path" ]; then
    count="$(rg --files --hidden -g '!.agent.*' -g '!*.log' "$path" 2>/dev/null | wc -l | tr -d ' ')"
    printf '%s: %s files\n' "$rel" "$count"
  else
    printf '%s: MISSING\n' "$rel"
  fi
done

# skills：目录完整性、frontmatter、技能表与镜像；空/不完整目录不能被文件扫描漏掉。
find "$REPO_ROOT/skills" -mindepth 1 -maxdepth 1 -type d -print 2>/dev/null |
while IFS= read -r d; do
  [ -f "$d/SKILL.md" ] || printf 'MISSING SKILL.md: %s\n' "$d"
  [ -f "$d/AGENTS.md" ] || printf 'MISSING AGENTS.md: %s\n' "$d"
done

rg --files --hidden -g 'SKILL.md' "$REPO_ROOT/skills" 2>/dev/null |
while IFS= read -r f; do
  d="${f%/SKILL.md}"
  name="${d##*/}"
  rg -q "^name: $name$" "$f" || printf 'NAME MISMATCH: %s\n' "$f"
  [ -f "$d/AGENTS.md" ] || printf 'MISSING AGENTS.md: %s\n' "$d"
done

# tools/hooks：只列真实文件，排除运行日志和缓存；脚本语法在 Step 6 验证。
rg --files --hidden -g '!.agent.*' -g '!*.log' "$REPO_ROOT/tools" "$REPO_ROOT/hooks" 2>/dev/null | sort

# plugins：查找 manifest/入口，不把空目录或日志当成插件。
rg --files --hidden -g '!.agent.*' -g '!*.log' "$REPO_ROOT/plugins" 2>/dev/null | sort

# 占位符匹配需人工分类；命令示例和规范中的字面量不是自动判定的缺陷。
rg -n 'TBD|TODO|FIXME|实现细节后补|待补充' \
  "$REPO_ROOT/skills" "$REPO_ROOT/tools" "$REPO_ROOT/hooks" "$REPO_ROOT/plugins" 2>/dev/null || true

• 输出摘要：四树是否存在及文件数、技能目录完整性、frontmatter 一致性、脚本/清单类型、 占位符匹配和技能表登记情况。空目录与缺失目录必须分别报告。
• skills/ 分三层检查：SKILL.md 的触发描述与固定章节、同目录 AGENTS.md/references、 skills/AGENTS.md 的技能表/互鉴表/计数；不因“这是文档”跳过结构核验。
• tools/ 检查命令入口、shebang、帮助/退出码、依赖与幂等性；hooks/ 额外检查触发时机、 执行顺序、可执行权限、重复执行和秘密泄露风险；plugins/ 检查 manifest、入口、版本/依赖、 权限和加载兼容性。只读基线阶段不运行有副作用的 hook 或 plugin。
• 以 skills/AGENTS.md 为本地基准（参考基线，先读后分析）： ① 技能表（| 技能 | 用途 |）= 每个技能核心点的权威登记，差距分析逐技能对照 技能表行与 SKILL.md 现状是否脱节（核心点变更未同步即差距）； ② 互鉴表 = 各技能标志性优点清单，升级时检查"该优点是否已借鉴到适用技能"； ③ 范式总览 = 文档结构与执行范式标准，验证时逐项对齐； ④ 跨技能调用约定 = 新技能/改动须维护「与其他技能配合」条目（19/19）。 任何更新完成前，对照技能表核对登记是否同步（本技能自己的 Step 6 验证也含此项）。

Step 3. 多源最佳实践调研与热榜检索（失败一直重试）

3.1 参考源与排序接口

以上来源是“发现候选”和“核对规则”的不同层：热榜只决定先看谁，规范/官方/社区原文才决定是否吸收。 外部页面可能调整参数，执行时以接口返回和当前文档为准，并在终端记录实际 URL、HTTP 状态和读取时间。

3.2 热榜执行配方

1. 从升级主题提取一个不含机密的查询词；所有代码托管源使用同一查询语义，并通过 --data-urlencode 编码，避免手工拼接 URL。热榜默认开启，每源取前 N（默认 10）。

2. 先请求机器接口，再请求网页回退；例如 GitHub 的可执行请求为：

   QUERY='agent skills'
   curl --fail --location --silent --show-error --max-time 30 --get \
     'https://api.github.com/search/repositories' \
     --data-urlencode "q=$QUERY" --data 'sort=stars' --data 'order=desc' --data 'per_page=10'

   Gitee 将 sort 换为 stars_count，GitLab 将接口换为 /api/v4/projects 并使用 order_by=star_count&sort=desc，Codeberg 使用 sort=stars&order=desc。

3. 解析器先检测 jq；不可用时使用 Python 标准库或当前环境已有的等价解析器，不自动安装 依赖。解析失败属于本地工具问题，应先换解析器，不得误报为网站不可达。

4. 将结果归一化为 来源 | 项目 | stars | forks | 更新时间 | URL | HTTP 状态 | 获取时间， 每个来源内部按原生 star 数降序；跨源展示必须保留来源和原始字段，不能宣称不同平台的 star 可直接比较。星数相同按更新时间倒序，并保留并列。

5. 对榜单前 N 个候选逐一核对实际 skill/配置内容、许可证、近期提交、兼容性和安全边界； 仅因 star 高而采纳属于不充分证据。来源清单必须写出 URL、仓库/技能名、吸收点和未采纳理由。

3.3 重试与来源降级

• 连接、超时、DNS、TLS 或响应解码失败：按“API → 官方网页 → 备用域名/API → 延长超时” 顺序持续重试，直至成功或用户终止；在终端输出每次 URL、错误类别和第几次尝试。
• HTTP 401/403/404、参数不支持或权限不足不是连接失败：切换该来源的网页/文档回退， 记录状态并继续保留其他来源结果；不得伪造榜单，也不得把 [] 空结果改写成“找到候选”。
• 访问接口只用 GET；令牌只能从已有环境变量/凭据机制读取，不写入 URL、日志、补丁或总结。
• 若某源网页无法机器解析，仍可作为人工核对来源，但在结果中标记“未取得结构化排名”； 若用户指定该源为必需来源，继续重试直到成功或用户终止。

Step 4. 差距分析（对照表）

按四类目标树和参考层分别形成差距表；skills 关注文档/触发/联动，tools 关注命令接口与 可维护性，hooks 关注生命周期与安全，plugins 关注清单/入口/兼容性。每个差距都要能回指 本地文件、外部 URL 或本次命令输出：

• 只列入有实据的差距；已覆盖的方法论标"已覆盖"不动作；
• 无对应 skill/tool/hook/plugin 且确有价值 → 列为"新增"候选，评估后再建；空目录本身不是新增理由；
• 差距按类型标注动作：内容/结构差距 → 优化/补充/debug（本技能直接执行）； 性能/效率差距（技能执行慢、命令开销大、流程冗余）→ 标注 optim 动作， 转 optim 技能处理（先测量基线再优化，收益量化，不凭感觉"改快"）； 差距类型在动作列显式写出（补充/debug/optim），便于执行与验证对照。

Step 5. 执行（最小改动）

按差距表逐项处理，遵循本目录既有格式约定，并按目标树选择最小改动：

1. 优化：改差距所在处，不重构无关部分；内容/结构优化直接执行， 性能/效率类优化转 optim 技能——先测量基线（3-5 次取中位数，记录原始序列）→ 主导项分析（复杂度/调用开销/IO/启动）→ 最小改动 → 复测对比，收益量化记录 （基线 → 优化后），不虚报收益；optim 的测量与复测数据在终端摘要中说明；
2. 补充：在既有 SKILL.md、工具说明、hook 说明或 plugin manifest 对应位置加入缺失内容， 标明来源和适用条件；
3. 新增：只有差距表证明确有缺口才新建 skills/<name>/SKILL.md + AGENTS.md（3-7 行）， 或新建目标树所需的真实入口/清单；技能新增还要更新 skills/AGENTS.md 技能表登记；
4. debug：修复发现的格式、完整性、逻辑、权限或加载问题；不以“换平台”掩盖根因；
5. 借鉴内容注明出处（网站 + 仓库/技能名 + URL），不照搬不署名。

Step 5.3 插件推荐与一键安装流程（目标包含 plugins 推荐/安装器时启用）

当用户要求“添加更多插件推荐”“提供一键安装脚本”或维护 plugins/README.md 时，按以下边界 执行；推荐清单和安装器是两个产物，前者不能隐式触发后者：

1. 核对候选：从多源热榜和明确的官方/上游仓库发现候选，逐项读取实际 .codex-plugin/plugin.json、marketplace manifest、许可证、安装说明和近期兼容性；区分 “原生 Codex marketplace 插件”“可转换的 Agent Skills 集合”和“仅 MCP/其他 harness 工具”， 不因 star 高就把后两类写成原生插件。
2. 写推荐条目：每项记录网站、仓库/插件名、URL、版本或 ref、许可证、实际能力、适用场景、 与本库的重叠/权限风险和可复现安装入口；无法确认 manifest、许可证或安装命令时列入暂不纳入， 写明证据和原因。官方、社区和相邻工具分组，避免把不同信任等级混成一张榜单。
3. 设计安装器：只调用目标 harness 已验证的安装接口——Codex 当前为 codex plugin marketplace add + codex plugin add；opencode 为 opencode plugin <npm模块>，并把模块写入 opencode.json 的 plugin 数组 （无 marketplace 命令，安装器设计不能照搬 Codex；参考本技能 references/awesome-opencode.md 对接点 1）。提供默认有限 profile、按名安装、 --dry-run、可选 Git ref 和 --help/--list。安装器不得在仓库加载时自启，不复制第三方源码， 不创建个人 marketplace，不删除已有插件，不隐式安装 npm/系统依赖，不自动信任 hooks；带 hooks、 MCP 或大规模重叠技能的项目只能显式选择，并在输出中警告。
4. 保持幂等与可审查：重复运行先复用已配置 marketplace，安装后用 CLI 的 JSON 查询验证注册； 多目标安装逐项报告并继续处理，最后以非零退出码汇总失败项。对上游使用 main 时支持 ref 覆盖， 文档同时给出 tag/commit 固定方式。wshobson/agents 等需要额外生成器或 npm 工具的项目， 不得伪装成通用原生安装路径，可保留人工安装说明。
5. 同步说明：更新 plugins/README.md 与 plugins/AGENTS.md，写清脚本不会被本库自动调用；若 安装器改变了 Codex 配置入口，再核对相关 skills 的调用说明和安全边界。实际安装只有在用户明确 要求执行时进行；本任务只提供脚本时不替用户写入 CODEX_HOME。

Step 5.4 up 的自我进化（目标包含 up 时启用）

自我进化是把可复现经验转为更好的规则，不是让技能无边界地改写自己：

1. 收集证据：只使用本次运行的基线结果、来源 HTTP/解析结果、失败与重试记录、差距表、 验证输出和用户明确反馈；一次性环境噪声、猜测和未读取的历史不作为改进依据。
2. 生成候选：把问题归入“触发遗漏、范围遗漏、来源/排序错误、步骤不可执行、验证盲区、 安全边界缺失”之一，写成 证据 → 可复现条件 → 拟改规则 → 预期收益 → 风险 → 验证方法。 一个确定性失败，或两个相互独立的观察即可提出候选；没有证据就记录“无候选”。
3. 保留不变量：候选不得删除四树范围、多源热榜、失败重试、差距表、验证闭环、安全边界、 不提交/不推送和镜像同步等既有契约；不得把临时 URL、令牌、运行日志或机器特征写进技能。
4. 单轮单变更：每轮最多采纳一个候选，只改 skills/up/SKILL.md 及其必要的技能表、 AGENTS.md 和 .opencode/skills 镜像；不在自我进化轮中顺带改其他技能。在终端摘要中记录 采纳/拒绝理由与验证证据，不创建过程记录文件。
5. 回归与停止：改动后重跑结构检查和三类真实提示词（四树升级、多源 star 热榜、up 自改）； 候选未改善行为、破坏不变量或验证失败则修正该候选并保留遗留项。一次 up 调用最多进行一轮 自我进化，下一轮只在出现新证据时继续，避免递归自改和无效空转。

Step 5.5 内部联动（四树变更后必做）

外部差距动作和自我进化完成后，按“内部三查 + 双目录”联动本库：

1. 调用链推广：检查全部技能「与其他技能配合」条目与 all/make 编排矩阵；新场景缺失即补 1-2 行。四树中的 tool/hook/plugin 若改变技能入口，也要核对相关技能的调用说明和安全边界；
2. 互鉴检查：对照「各技能优点互鉴」表逐项核对适用技能——已落地记“已覆盖”，未落地且 有实据才补入；无新差距时如实记录核对数量；
3. 技能表核对：skills/AGENTS.md 的技能行、互鉴表和技能计数与所有 SKILL.md 核对； up 核心点变化必须同步更新 up 行，新增 skill 才增加计数，不因 tools/hooks/plugins 文件增加 而虚增 skill 数；
4. 双目录同步：skills/ 变更全部镜像到 .opencode/skills/（若该加载镜像存在），对每个 改动文件执行 cmp；镜像缺失或不一致必须报告并修复，不把镜像当作第二个独立版本。

Step 6. 验证

每处改动后核验（结构验证必做，行为验证按改动性质做）：

1. 结构验证（每次必做）：SKILL.md 的 frontmatter 完整（name/description/metadata）、 name 与目录一致、固定章节齐备、行数合理（参考 <500 行分级披露）、技能表登记正确； tools/hooks 的 shell 文件用其实际解释器做 bash -n/等价语法检查并核对可执行权限， plugins 的 JSON/YAML manifest 用已有解析器校验入口、版本和依赖；占位符匹配逐条分类， 不把命令示例字面量误判为缺陷；
2. 触发描述检查（每次必做，吸收 writing-skills SDO）：description 以 触发条件为主（"当用户要求…" + 具体触发词/场景），不得总结工作流—— 描述总结工作流时 agent 可能只按描述执行而跳过正文（SDO 实测结论）； 发现违规即在差距表登记并精简，工作流细节留在正文；触发词覆盖"pushy" （对抗少触发倾向）；
3. 行为验证（新增/大改目标必做，纯措辞级改动可选）：用 2-3 个真实用户口吻的提示词 试跑——至少覆盖“四树升级”“多源 star 热榜”“up 自我进化”；检查命令是否真实可执行、 步骤是否无歧义、触发描述是否覆盖场景。热榜验证要保留每源 HTTP 状态、排序参数、前 N 结果和解析器；空结果、网页回退和连接失败必须分开标注（吸收 writing-skills 的 TDD 式 技能测试思想，完整有/无技能对照评估转 skill-creator）； 性能类改动（Step 5 标注 optim 动作的差距）验证时须附 optim 实测对比 （基线 → 优化后的测量数值，3-5 次取中位数），无对比数据视为未验证；
4. 修改回归（修改既有技能后必做）：git diff 复查改动仅含预期内容， 未破坏原结构（冲突标记/意外删除/格式破坏检查）；
5. 内部联动核对（新增/大改技能或入口后必做）：调用链推广覆盖（配合条目与矩阵 grep 核对，无遗漏可调用场景）、互鉴表登记、技能表/计数同步、双目录 cmp 一致； 四树中只有实际新增 skill 才改变技能计数——逐项在终端摘要中说明；
6. 自我进化验证（启用自我进化时必做）：核对候选是否来自本次证据、是否只改一个边界 明确的规则、是否保留不变量，并确认回归提示词能命中新的路径；候选无证据或失败时不得 写入正式规则；
7. 验证结果逐项在终端摘要中说明，不虚报“已验证”。

Step 7. 收敛评估

• 差距表全部动作完成且验证通过 → 收敛，进入 Step 8；
• 存在未落实差距（如网络失败被用户终止）→ 如实列入遗留项；
• 热榜只在取得结构化排序或明确标注网页/空结果时算完成；单一来源成功不等于多源调研完成；
• 自我进化在本轮无证据候选、候选已验证，或已完成一次单轮变更并通过回归时收敛；
• 收益微小项报告权衡，由用户决定取舍。

Step 8. 总结（结构化输出）

✓ up 升级完成
   目标:   <任务定义；目标树与是否启用热榜/自我进化>
   来源:   <各网站/仓库/技能名 + URL + 吸收点；各源重试次数与状态>
   热榜:   <每源查询词、排序字段、前 N 结果；空结果/网页回退如实标注>
   差距:   <N 项差距全部处理 / 遗留 M 项>
   优化:   <技能名: 文件:行号 <说明>，无则省略>
   补充:   <同上>
   新增:   <技能名: 文件:行号 <说明>，无则省略>
   debug:  <同上>
   自进化: <候选证据、采纳/拒绝理由、回归结果；无候选则写“无候选”>
   验证:   <检查项逐项通过情况>
   收敛:   <差距表清零/收益微小/用户终止>
   遗留:   <未落实项/待用户确认项，无则省略>

反合理化表（跳过验证/直接动手的借口 → 现实）

以上任一出现 = 停下，补验证。

错误处理

注意事项

• 本地基线、差距表、验证结果均以实测为准，不编造；
• 网络重试按用户要求执行直至成功，但向用户报告各来源重试进展；
• 借鉴外部实践注明出处（网站 + 仓库 + 技能名 + URL），不照搬不署名；
• 热榜查询只读、默认按各来源原生 star 降序；不把榜单排名当成安全或质量批准；
• 四类目录均属 agent 配置对象；日志、缓存、依赖目录和生成物只在基线中排除并说明；
• 自我进化只吸收当前证据支持的通用规则，一轮一个候选，不创建过程记录文件，不修改无关技能；
• 不越界访问工作目录之外的内容；
• 不删除文件（用户未明确要求时）；本次改动按公共 Git 契约检查，不自动暂存、提交或推送；