# Create Repo Skill

Create or update a skill in this repository the right way, canonical home in...

- Repository: https://github.com/every-app/open-seo (25988 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add every-app/open-seo --skill create-repo-skill -g -a claude-code -y`
Codex: `npx skills add every-app/open-seo --skill create-repo-skill -g -a codex -y`
Cursor: `npx skills add every-app/open-seo --skill create-repo-skill -g -a cursor -y`
Gemini CLI: `npx skills add every-app/open-seo --skill create-repo-skill -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add every-app/open-seo`

## Description

Create or update a skill in this repository the right way, canonical home in .agents/skills, internal-vs-public marking, symlink mirroring into .claude/skills, and public docs registration for product skills. Use whenever adding a new skill, converting a workflow into a skill, or when .claude/skills and .agents/skills look out of sync.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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` (created by the `skills` CLI on first vendor). 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:

The rest: https://github.com/every-app/open-seo/blob/HEAD/.agents/skills/create-repo-skill/SKILL.md