mcpField
C
create-repo-skill

create-repo-skill

github.com/every-appAgent 工作流25.5k319 次安装2 天前更新
代码仓库

关于 create-repo-skill

用于在 OpenSEO 仓库中创建和登记 Agent 技能的内部指南，面向维护者。它规定了规范目录、镜像方式、审核要求及公共技能的发布流程。

主要功能

  1. 01规定技能的规范目录
  2. 02说明 Claude Code 符号链接规则
  3. 03管理外部技能锁定文件
  4. 04列出公共技能登记步骤
  5. 05提供同步检查方法

适用场景

  1. 01在仓库中新增内部技能
  2. 02发布面向用户的 SEO 技能
  3. 03检查 Claude Code 技能镜像是否漂移

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/every-app/open-seo --skill create-repo-skill

安装后在 Claude Code 中输入/create-repo-skill确认已加载。

详细介绍

创建仓库技能

布局（不变量）

  • .agents/skills/<kebab-name>/SKILL.md 是每个技能唯一的规范存放位置——包括面向公众的产品技能（客户安装的 SEO 工作流）和内部仓库技能（如 merge-ready、papercuts 以及本技能等 Agent 工作流）。用户通过 npx skills add every-app/open-seo 从此目录安装。
  • .claude/skills/ 仅包含指向 .agents/skills/ 的符号链接——每个技能一个，供在此仓库中工作的 Claude Code Agent 自动加载。切勿复制文件：.agents/skills/ 被 prettier 忽略（供应的技能使用哈希固定），而 .claude/skills/ 不会被忽略，因此副本会在 .claude 目录下被重新格式化，导致两个目录树出现差异——在符号链接成为规则之前，三个技能就发生过这种情况。prettier --check . 不会遍历符号链接，因此符号链接在结构上始终与其规范源文件逐字节一致。
  • 供应的技能（来自外部）会在 skills-lock.json 中通过哈希固定（首次供应时由 skills CLI 创建）。切勿手动编辑供应技能的内容；请使用 skills CLI 重新供应，以确保锁定哈希仍然有效。
  • .agents/skills/** 属于审查控制平面（参见 AGENTS.md）：更改需要通过 CODEOWNERS 由维护者明确审查。请在分支上进行更改，并在 PR 中特别说明——切勿将技能修改视为顺带变更。

创建 skill

  1. 执行 mkdir .agents/skills/<kebab-name>，并编写带有 frontmatter 的 SKILL.md：

    ---
name: <kebab-name>            # must match the directory name
description: <what it does + explicit "use when ..." triggers>
metadata:
  internal: true              # ONLY for internal repo skills — omit for product skills
---

  2. 确定 skill 的类型：

    • 仓库内部 skill（Agent／开发工作流）：设置 metadata.internal: true。不要在任何公共入口注册它。如果仓库 Agent 应自动加载它，请添加镜像符号链接：

      ln -s ../../.agents/skills/<name> .claude/skills/<name>

    • 公共产品 skill（面向客户的 SEO 工作流）：不设置 internal 标记，通常也不添加 .claude/skills 符号链接（仓库 Agent 不需要客户工作流）。公共 skill 会自动提供给 SAM，即应用内的实时 Agent——此标记采用失效开放策略，因此缺少 internal: true 会导致面向仓库开发的指令发送给最终用户。为其添加标准的“Project context”前言（复制一个同级 skill，例如 seo-audit），并包含该 skill 所需的章节；同时在用户查找 skill 的所有位置注册它：

      • src/server/features/sam/samSkills.test.ts — 将名称添加到固定的公共清单中（否则测试会失败；该失败就是保护机制）
      • web/content/docs/skills/<name>.mdx — 文档页面（参照同级页面，例如 competitor-analysis.mdx：说明其用途、适用时机、返回内容，以及如何获得最佳结果）
      • web/content/docs/skills/index.md — 在相应的工作流章节中添加项目符号
      • web/content/docs/skills/meta.json — 导航条目
      • src/routes/_app/ai.tsx — SKILL_NAMES
      • .agents/skills/seo-coach/SKILL.md — 在“What each workflow does”清单中添加一行
      • plugins/openseo/skills/<name> — 将 skill 添加到 scripts/sync-plugin-skills.mjs 中的 skills 列表，然后运行 pnpm sync-plugin-skills（此目录存放真实副本，而非符号链接——Claude Code 和 Codex 插件会从这里打包；Codex 安装程序会静默跳过符号链接文件，因此符号链接会导致打包的插件缺少 skill）。pnpm ci:check 会重新运行同步，并在内容不一致时失败，因此这里漏掉的更新会被发现；但下面提到的 skill 数量和清单是说明文字，不会被检查——请手动更新：plugins/openseo/*/plugin.json 中的两个 description 字段、Codex 清单的 interface.longDescription，以及 web/content/docs/claude-code-plugin.md 和 web/content/docs/codex-plugin.md 中的 skill 列表
      • 可选：如果适合放在营销或设置页面中，还可更新 web/src/lib/feature-pages.ts 和 web/content/docs/skills/setup.md

  3. 如果 skill 引用了 MCP 工具，请使用准确的工具名称，并确保其与 src/server/mcp/server.ts 中的名称保持一致——skill 中的工具名称对遵循指令的 Agent 至关重要。对于公共 skill，还要检查 src/server/features/sam/samChatTools.ts：SAM 的工具集经过精选，而 skill 中提到但 SAM 不具备的工具会导致应用内 Agent 无法继续执行。

  4. 运行 pnpm format:write（会处理文档页面；.agents/skills 本身有意不作格式化），然后提交。公共 skill 的文案应遵循 openseo-review-web-content 标准。

同步检查（有疑问时，以及每次更改 skill 后运行）

for d in .claude/skills/*/; do n=$(basename "$d")
  [ -L "${d%/}" ] || echo "DRIFT RISK — not a symlink: $n"
  [ -e ".agents/skills/$n" ] || echo "BROKEN — no canonical source: $n"
done

对于任何被标记的内容：将规范内容移至 .agents/skills/<name>/（先对比两侧的差异，有意协调冲突，并以最新意图为准），删除 .claude 副本，然后替换为符号链接。

评论

支持 Markdown