create-lang-dev-skill

What this skill does

# Create Language-Dev Skill

Use this skill when the user wants to **create a new language-specific development skill** for their project (e.g., rust-dev, go-dev, python-dev, java-dev).

## Overview

A lang-dev skill captures the conventions that live in reviewers' heads — the patterns that linters and formatters can't enforce. This skill guides you through a systematic process to extract those conventions and produce a high-quality skill file.

**Target output:** The final skill file should be **under 500 lines** — scannable, not encyclopedic. Keep this constraint in mind throughout every phase so you collect the most impactful conventions rather than exhaustively cataloging everything.

## Phase 1: Discovery — Understand the Landscape

### 1.1 Find the language footprint

Identify all files for the target language and map the directory structure.

```
- Count total files (e.g., *.rs, *.go, *.py)
- Identify major modules/packages/crates
- Map the directory tree by domain (CLI tools, libraries, services, etc.)
```

**What to look for:**
- How many files exist? (< 50 = small footprint, 50-500 = medium, 500+ = large)
- Are they concentrated in one area or spread across the repo?
- Is there a workspace/monorepo structure?

#### Monorepo considerations

If the project is a monorepo with multiple packages, services, or crates:
- Determine whether conventions are **repo-wide** or **per-package**. Some monorepos have different teams and styles per subdirectory.
- Check for a top-level build config (e.g., root `Cargo.toml` workspace, Go workspace `go.work`, Bazel `WORKSPACE`) that unifies builds.
- Ask the user whether the skill should cover the **entire repo** or a **specific subtree**. Scoping to a subtree keeps the skill focused and under the 500-line target.
- When mining PRs later (Phase 2), filter by the relevant path prefix to avoid mixing conventions from unrelated parts of the repo.

### 1.2 Identify the build system

Determine how the language is built, tested, linted, and formatted. **Do not assume** — verify each claim against actual config files and CI pipelines.

**Check these in order:**
1. Build config files (BUILD/BUILD.bazel, Makefile, package.json, pyproject.toml, go.mod, etc.)
2. CI pipeline configs (.circleci/, .github/workflows/, Jenkinsfile, etc.)
3. Formatter/linter configs (.eslintrc, .golangci.yml, clippy.toml, ruff.toml, etc.)
4. Root-level scripts or Makefiles that wrap build commands

**Key questions to answer:**
- What is the canonical build command? (e.g., `bazel build`, `go build`, `npm run build`)
- What is the canonical test command?
- What is the canonical lint command? Is linting separate or integrated into the build?
- What is the canonical format command?
- Can the native language toolchain be used (e.g., `cargo test`, `go test`), or must you use the build system (e.g., `bazel test`)? **Verify this — don't assume.**

### 1.3 Ask for team documentation

**Always ask the user** if they have internal documentation. This is often the most valuable source.

Prompt the user with:
> Do you have any of the following for this language?
> - Wiki/Confluence pages about development conventions
> - Style guides or coding standards documents
> - Onboarding docs for new developers
> - ADRs (Architecture Decision Records)
> - README files in language-specific directories
>
> These are often the most authoritative source for conventions that go beyond linters.

If documentation exists, use it as the **primary source of truth** — it overrides patterns inferred from code alone.

## Phase 2: Mine PR Reviews — The Core Value

This is where the most valuable, non-obvious conventions live. Linters catch syntax; PR reviews catch design.

### 2.1 Find PRs that touch the target language

The examples below use the GitHub `gh` CLI. If the project uses **GitLab** (`glab`), **Bitbucket**, or another platform, adapt the commands to the equivalent API. The key data you need is the same: a list of merged PRs with their review comments.

```bash
# Get recent merged PRs (adjust owner/repo)
gh pr list --state merged --limit 100 --json number,title,files

# Filter for PRs touching the target language files
# Look for .rs, .go, .py, .java, .ts, etc.
```

**Target: 15-30 PRs with substantive review comments.** If fewer exist, the language may be too new in the project for a full skill — supplement with `git log --all --follow` history and `git blame` archaeology on key files to surface conventions that predate formal code review. Note this limitation in the final skill.

### 2.2 Extract review comments

```bash
# Get the repo owner/name
gh repo view --json owner,name

# For each PR, get inline review comments
gh api repos/{owner}/{repo}/pulls/{pr_number}/comments
```

### 2.3 Categorize comments

Classify each comment into one of these buckets. **Ignore** anything that a linter or formatter would catch automatically.

| Category | What to Look For |
|----------|-----------------|
| **String/formatting patterns** | Format string conventions, logging patterns |
| **Error handling** | Error propagation style, context/wrapping, fail-fast vs. graceful |
| **Architecture** | Module organization, separation of concerns, layer boundaries |
| **Naming** | Semantic naming rules, domain-specific terminology, URL/API naming |
| **Type design** | Generic vs. concrete types, ownership/borrowing, interface design |
| **Testing** | Test expectations, test isolation, mocking patterns, what to test |
| **Logging/observability** | Which logging framework, structured vs. unstructured, log levels |
| **Configuration** | Hardcoded vs. configurable, defaults, env vars vs. flags |
| **Dependencies** | Preferred libraries, version management, internal vs. external |
| **Code organization** | File layout, module boundaries, shared code extraction |
| **Build system** | Build target patterns, visibility rules, CI integration |
| **Documentation** | Doc comment expectations, what needs docs, example requirements |
| **Performance** | Unnecessary allocations, cloning, concurrency patterns |
| **Security** | Input validation, secret handling, auth patterns |

These are common categories, but let the actual PR comments drive the taxonomy. Create new categories if a project has a dominant pattern not listed here (e.g., "migration patterns" for a database-heavy project, or "FFI boundaries" for a mixed-language codebase).

### 2.4 Count and rank

For each category, record:
- **Frequency**: How many times it appeared across PRs
- **Reviewers**: Which reviewers raised it (identifies subject-matter experts)
- **Example quotes**: Direct quotes from the most clear/representative comments

**Rank categories by frequency.** The top 5-7 categories become the core sections of the skill.

## Phase 3: Verify — Trust but Check

**Every claim in the skill must be verified against the actual codebase or documentation.**

### 3.1 Verify build commands

First, **inspect configuration files** (BUILD files, Makefiles, CI configs, `package.json` scripts, etc.) to verify every command you plan to document. Check that:
- The build target exists
- The target name is correct (e.g., `:lib_test` vs `:my_crate_test`)
- The format command includes this language
- Linting is integrated into the build or is a separate step

If inspection alone is ambiguous, run the commands to confirm — but prefer reading config files as the primary verification method, since running commands may have side effects or require environment setup.

### 3.2 Verify conventions against code

For each convention from PR reviews, check if the codebase actually follows it:
- Search for counter-examples (code that violates the convention)
- If violations are widespread, the convention may be aspirational, not enforced — note this
- If violations are rare and recent PRs fix them, the convention is real

### 3.3 Cross-reference with documentation

If the user provided wiki/docs, check for contradictions between:
- What PR reviewers say
- What the