/create-project-skills

name: create-project-skills
description: "Scans an existing codebase and generates project-specific skills that capture inferred conventions such as naming, file organization, framework usage, data access, error handling, and testing style. Writes into the project's chosen skill directory (e.g., `.claude/skills/`, `.agents/skills/`, or a custom path). Use when the user asks to \"extract skills from the codebase\", \"create project skills\", \"infer project conventions as skills\", \"codify patterns as skills\", or \"mine the repo for best practices\"."

Create Project Skills

Generates one skill per detected convention area in the project's skill directory so future Claude or Codex sessions auto-load them when working in the repo.

Task Tracking

At the start, use `TaskCreate` to create a task for each phase:

1. Survey codebase 2. Extract patterns in parallel 3. Evaluate patterns 4. Propose skill list 5. Run `/create-skill` skill

Step 1: Survey Codebase

If `$ARGUMENTS` specifies paths, scope the scan to those paths; otherwise scan the whole repository.

Build the extraction context:

1. Detect primary languages and frameworks from manifest files (`package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `Package.swift`, `pom.xml`, `Gemfile`, and others appropriate to the stack). 2. Map the top-level source directory structure and note test directory conventions. 3. Read `CLAUDE.md`, `.claude/rules/`, `AGENTS.md`, and any `.cursor/rules` or `.cursorrules`. Note the conventions already documented there. The generated skills must not duplicate them. 4. Determine the target skill directory:

• Check candidate paths `.claude/skills/` (Claude Code), `.agents/skills/` (Codex), and a top-level `skills/` directory (match case-insensitively so `Skills/` or similar non-standard casing is detected too). Resolve symlinks so co-linked paths are treated as one logical location.
• Use `AskUserQuestion` to confirm where generated skills should live. List each distinct resolved location as an option, noting any symlink alias in the option description. If `.claude/skills/` is not among the detected locations, include it as a default option. The auto-added "Other" option lets users specify a custom path such as a project-specific directory.

5. In the chosen target directory, list existing skills. For each, record the skill name, the description from SKILL.md frontmatter, and the first `##` section heading from the body. These signals feed rename-conflict detection in Step 3.

Output a short text summary of detected stack, top-level layout, chosen target directory, and existing skills before moving on.

When that summary shows no source code to extract conventions from, stop here rather than dispatching Step 2. Executable code in any language qualifies, including scripts no manifest declares, so judge from the directory map rather than the detected stack. Documentation, instruction files, and configuration alone do not: extraction run over prose returns that prose's assertions as observed conventions, and Step 3 scores them with no code sites to test them against.

State that as text first — what the survey found, and that conventions extracted from it would have nothing to verify against. Then use `AskUserQuestion` to offer:

• **Write the skills from what we know (Recommended)** — build skills from what this session established, rather than from conventions read out of the repo
• **Generate nothing yet** — leave skills until the repo has code to have conventions about
• **Extract anyway** — generate skills from the documentation and configuration that are there

On the first option, run the `/create-skill` skill directly on that knowledge and skip the remaining steps. On either of the first two, mark the extraction phases cancelled so they no longer read as pending work.

Step 2: Extract Patterns in Parallel

Read [references/pattern-extractor.md](references/pattern-extractor.md) to see the full taxonomy of pattern categories. Decide which categories apply to the detected stack (e.g., drop "Styling and UI" for a backend service, drop "State management" for a static-analysis tool).

Emit all extraction Agent tool calls below in one assistant message. Each Agent call uses `model: "opus"` and no `name`. Wait for every agent to report before continuing. Do not begin the next step on a partial set, and do not relaunch an agent that has not yet reported. Launch one Agent per applicable category and state the total count explicitly when emitting the calls. Every agent's prompt must direct it to treat the shared working tree and its git index as read-only and to extract by reading and reasoning. HEAD stays where it is: read other refs with `git show <ref>:<path>` rather than `git checkout` or `git switch`. Each agent's prompt must:

• Name its assigned category
• Include the stack summary and directory map from Step 1
• Include the list of conventions already documented in `CLAUDE.md` and `.claude/rules/` so duplicates are skipped
• Instruct the agent to read [references/pattern-extractor.md](references/pattern-extractor.md) as its role brief and return findings in the format defined at the end of that file

Step 3: Evaluate Patterns

Aggregate findings from all agents. For each finding, score three axes:

• **Consistency**: what share of eligible sites follow the pattern? Drop findings below 30%. Flag findings between 30–70% as "mixed" for Step 4 review.
• **Intentionality**: does the pattern appear across multiple subsystems and recent commits, or is it isolated? Drop findings confined to a single legacy module unless docs or lint config explicitly mark them as the desired convention.
• **Modernity**: does the pattern align with current best practices for the stack? Flag patterns that contradict current idioms (e.g., pre-hooks class components in a React codebase also using hooks elsewhere) as "legacy" for Step 4 review.

Group the surviving findings by topic into candidate skills.