create-repo-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create a repo skill

创建仓库Skill

The layout (invariants)

目录结构（不变规则）

.agents/skills/<kebab-name>/SKILL.md
is the only canonical home for every skill — public product skills (SEO workflows customers install) and internal repo skills (agent workflows like
```
merge-ready
```
,
```
papercuts
```
, this one) alike. Users install from this tree via
```
npx skills add every-app/open-seo
```
.
.claude/skills/
contains only symlinks into
.agents/skills/
— one per skill that Claude Code agents working in this repo should auto-load. Never copy files:
```
.agents/skills/
```
is prettier-ignored (vendored skills are hash-pinned) while
```
.claude/skills/
```
is not, so a copy gets reformatted on the
```
.claude
```
side and the trees drift — this happened to three skills before symlinks became the rule.
```
prettier --check .
```
does not descend into the symlinks, so a symlink stays byte-identical to its canonical source by construction.
Vendored skills (external origin) are hash-pinned in
```
skills-lock.json
```
(currently only
```
webapp-testing
```
, from
```
anthropics/skills
```
). Never hand-edit a vendored skill's content; re-vendor with the
```
skills
```
CLI so the lock hash stays valid.
```
.agents/skills/**
```
is part of the review control plane (see
```
AGENTS.md
```
): changes require explicit maintainer review via CODEOWNERS. Make the change on a branch and call it out in the PR — never treat skill edits as incidental.

.agents/skills/<kebab-name>/SKILL.md
是所有Skill的唯一规范存储位置——无论是公开产品Skill（客户可安装的SEO工作流）还是内部仓库Skill（如
```
merge-ready
```
、
```
papercuts
```
以及本Skill这类Agent工作流）。用户可通过
```
npx skills add every-app/open-seo
```
从该目录安装Skill。
.claude/skills/
仅包含指向
.agents/skills/
的符号链接——每个链接对应仓库中Claude Code agents应自动加载的Skill。切勿复制文件：
```
.agents/skills/
```
已被prettier忽略（第三方Skill采用哈希固定版本），而
```
.claude/skills/
```
未被忽略，因此复制的文件会在.claude侧被格式化，导致两个目录内容不一致——在采用符号链接规则前，已有三个Skill出现过这种情况。
```
prettier --check .
```
不会遍历符号链接，因此符号链接会与规范源文件保持完全一致。
第三方Skill（外部来源）在
```
skills-lock.json
```
中采用哈希固定版本（目前仅有来自
```
anthropics/skills
```
的
```
webapp-testing
```
）。切勿手动编辑第三方Skill的内容；请使用
```
skills
```
CLI重新引入，以确保锁定哈希值有效。
```
.agents/skills/**
```
属于审核控制平面（详见
```
AGENTS.md
```
）：修改需通过CODEOWNERS获得维护者的明确审核。请在分支上进行修改，并在PR中说明——切勿将Skill编辑视为附带操作。

Creating a skill

创建Skill

mkdir .agents/skills/<kebab-name>

and write

SKILL.md

with frontmatter:

markdown

---
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
---

Decide which kind it is:
- Internal repo skill (agent/dev workflow): set
```
metadata.internal: true
```
  . Do NOT register it on any public surface. If repo agents should auto-load it, add the mirror symlink:
  bash
```
ln -s ../../.agents/skills/<name> .claude/skills/<name>
```
- Public product skill (a customer-facing SEO workflow): no
```
internal
```
  flag, usually no
```
.claude/skills
```
  symlink (repo agents don't need customer workflows). Register it everywhere users discover skills:
  - ```
  web/content/docs/skills/<name>.mdx
```
  — docs page (mirror a sibling like
```
  competitor-analysis.mdx
```
  : what it does, when to use it, what you get back, how to get the best result)
- ```
web/content/docs/skills/index.md
```
    — bullet in the right workflow section
  - ```
  web/content/docs/skills/meta.json
```
  — nav entry
- ```
.agents/skills/seo-coach/SKILL.md
```
    — one line in the "What each workflow does" roster
  - Optional:
```
web/src/lib/feature-pages.ts
```
    and
```
web/content/docs/skills/setup.md
```
    if it deserves marketing/setup placement
If the skill references MCP tools, use exact tool names and keep them in sync with
```
src/server/mcp/server.ts
```
— the tool names in skills are load-bearing for agents following them.
```
pnpm format:write
```
(covers the docs pages;
```
.agents/skills
```
itself is intentionally untouched), then commit. Skill prose follows
```
openseo-review-web-content
```
standards when public.

mkdir .agents/skills/<kebab-name>

并编写带前置元数据的

SKILL.md

：

markdown

---
name: <kebab-name>            # 必须与目录名称一致
description: <功能描述 + 明确的“适用场景...”触发条件>
metadata:
  internal: true              # 仅适用于内部仓库Skill——产品Skill请省略
---

确定Skill类型：
- 内部仓库Skill（Agent/开发工作流）：设置
```
metadata.internal: true
```
  。无需在任何公开平台注册。若仓库agents需自动加载该Skill，请添加镜像符号链接：
  bash
```
ln -s ../../.agents/skills/<name> .claude/skills/<name>
```
- 公开产品Skill（面向客户的SEO工作流）：无
```
internal
```
  标记，通常无需在
```
.claude/skills
```
  中创建符号链接（仓库agents无需使用客户工作流）。需在所有用户发现Skill的渠道进行注册：
  - ```
  web/content/docs/skills/<name>.mdx
```
  —— 文档页面（可参考同类文档如
```
  competitor-analysis.mdx
```
  ：包含功能、适用场景、返回结果、优化技巧）
- ```
web/content/docs/skills/index.md
```
    —— 在对应工作流章节添加项目符号
  - ```
  web/content/docs/skills/meta.json
```
  —— 导航条目
- ```
.agents/skills/seo-coach/SKILL.md
```
    —— 在“各工作流功能”列表中添加一行描述
  - 可选：若需营销/安装引导，可更新
```
web/src/lib/feature-pages.ts
```
    和
```
web/content/docs/skills/setup.md
```
若Skill引用MCP工具，请使用精确的工具名称，并与
```
src/server/mcp/server.ts
```
保持同步——Skill中的工具名称对执行该Skill的agents至关重要。
执行
```
pnpm format:write
```
（会格式化文档页面；
```
.agents/skills
```
本身有意不被处理），然后提交代码。公开Skill的文案需遵循
```
openseo-review-web-content
```
标准。

Sync check (run when in doubt, and after any skill change)

同步检查（存疑时或任何Skill修改后执行）

bash

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

Anything flagged: move the canonical content to

.agents/skills/<name>/

(reconciling differences deliberately — diff both sides first, newest intent wins), delete the

.claude

copy, and replace it with the symlink.

bash

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侧的副本，替换为符号链接。