Create a repo 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.

Creating a skill

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

2. 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
3. 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.

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

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

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