Add Skill

Steps

1. Determine domain prefix (the scope is required):

• Reuse the existing domain when one fits: list intelligence/skills/ and intelligence/agents/. If a domain prefix is already established for the target area (backend-, frontend-, devops-), use it. Introduce a new domain only when the scope is materially different from all existing ones.
• When no existing domain fits, derive from repo structure:
• Single / root project → use the project codename from intelligence/config.yaml → project.name
• Backend service / API component → backend-
• Frontend / web / UI component → frontend-
• Infrastructure, IaC, CI/CD, deployment → devops-
• Shared library / common / cross-cutting code → core-
• Test suites (e2e, integration) → tests-
• Tool-internal (intelligence-sync itself) → intelligence-
• If the repo is a monorepo with named components (e.g., apps/billing, services/auth), prefer the component name as the domain (billing-, auth-).
• Every skill needs a domain prefix. If the scope is unclear, ask the user before proceeding.

1. Determine naming: Build full name as <domain>-<verb>-<noun> using convention:

• add- — creates a single artifact (atomic)
• create- — orchestrates multiple add- skills (MUST use create-, never add-)
• update- — modifies existing files across stack
• run- — executes an operation (tests, build, sync)
• review- — read-only analysis

1. Check for existing agent: Find an agent in intelligence/agents/ matching the domain

• If found — this skill will be linked to that agent
• If not — ask user whether to create a new agent via /intelligence-add-agent first

1. Analyze codebase patterns: Read existing implementations to extract the repeatable steps this skill should automate. Each step must come from actual code patterns, not generic knowledge.

1. Create skill: Write intelligence/skills/<full-name>/SKILL.md with frontmatter:

   ---
   name: <full-name>
   description: "<what it does and when to use>"
   argument-hint: "<expected arguments>"
   agent: <matching-agent-name>
   ---

YAML safety (required): always wrap `description`, `argument-hint` and any other free-text string value in double quotes, regardless of content. Codex CLI uses strict YAML — an unquoted colon in description: Build retrospective: monthly parses as a nested mapping and the skill is rejected at startup. Quoting unconditionally removes the whole class of bug and makes lint trivial. If the value itself contains a double quote, escape it as \" or wrap the whole value in single quotes — e.g. description: 'Use as a quick "what do we have" view' — so an inner quote does not terminate the scalar early.

1. Write steps: Numbered, concrete, executable. Include verification (build/test) at the end. For orchestrators — reference atomic skills by name.

1. Update agent: Add skill name to the skills: list in the matching agent's frontmatter.

1. Run `/intelligence-sync` to distribute to all enabled IDE targets.