feat: add ai-ready skill with optimized frontmatter and sensei tooling

.claude/skills/ai-ready/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: ai-ready
+license: MIT
+metadata:
+  version: "1.2.0"
+description: '**WORKFLOW SKILL** — Analyze any repository and generate AI-ready configuration: AGENTS.md, CLAUDE.md, copilot-instructions.md, skills, CI workflows, issue templates. WHEN: "make this repo ai-ready", "set up AI config", "add copilot instructions", "prepare this repo for AI contributions", "generate AGENTS.md". INVOKES: file search, read, write/edit, gh CLI. FOR SINGLE OPERATIONS: write/edit files directly instead.'
+---
+
+# AI-Ready Repo Skill
+
+## Persona
+
+Adopt the perspective of an experienced repo maintainer who has managed high-traffic repos and reviewed thousands of PRs. Prioritize what **reduces review burden and contributor friction**. Every file you generate should earn its place — generic boilerplate creates noise.
+
+
+Follow these steps in order to analyze the current repository and generate all missing AI-ready configuration assets.
+
+**First run vs. re-run:** On the first run, most assets will be missing — the skill creates them. On re-runs, it **audits** existing assets against the current codebase, checking for drift, stale content, and new conventions from recent PR reviews. The skill **never overwrites existing files without user approval**.
+
+**Skipping assets:** If the user's prompt mentions skipping specific assets (e.g., "skip CI and issue templates"), respect those exclusions. Still run the full analysis, but skip generation for the excluded assets.
+
+**Report-only mode:** If the user asks for a report without generating files (e.g., "how ai-ready is this repo?", "score this repo"), run the full analysis (Steps 0–1) and display the report (Step 11) — but skip all generation steps (Steps 2–10).
+
+### The 12 tracked assets
+
+Assets are grouped into three categories. Count assets with **Nailed It** status for the score.
+
+**🤖 AI Context** — what AI agents read to understand your repo
+
+| # | Asset | Generated in |
+|---|-------|-------------|
+| 1 | `AGENTS.md` | Step 2 |
+| 2 | `.github/copilot-instructions.md` and/or `CLAUDE.md` | Step 3 |
+| 3 | Maintenance matrix (in `copilot-instructions.md` / `CLAUDE.md`) | Step 8 |
+| 4 | `.mcp.json` | Step 4b |
+| 5 | `.github/workflows/copilot-setup-steps.yml` | Step 4 |
+
+**🔧 Dev Workflow** — what keeps PRs clean and contributors on track
+
+| # | Asset | Generated in |
+|---|-------|-------------|
+| 6 | CI workflow (`.github/workflows/ci.yml`) | Step 5 |
+| 7 | Issue templates (`.github/ISSUE_TEMPLATE/`) | Step 6 |
+| 8 | PR template (`.github/PULL_REQUEST_TEMPLATE.md`) | Step 6 |
+| 9 | `.github/dependabot.yml` | (checked, not generated) |
+
+**📖 Onboarding** — what helps new contributors get started
+
+| # | Asset | Generated in |
+|---|-------|-------------|
+| 10 | README Contributing section | Step 7 |
+| 11 | Changelog (`CHANGELOG.md`) | Step 9 |
+| 12 | Documentation (or explicit "not needed" note) | Step 10 |
+
+**Scoring:** 🟩 Nailed It (counted) · 🟨 Could Be Better (not counted) · ⬜ Missing (not counted)
+
+| Medal | Name | Count | What it means |
+|-------|------|-------|---------------|
+| 🥉 | **Getting Started** | 1–4 | Basics in place but AI agents are mostly guessing |
+| 🥈 | **On Track** | 5–7 | AI agents can help but miss your conventions |
+| 🥇 | **Solid** | 8–10 | AI agents follow your patterns and catch most expectations |
+| 🏆 | **AI-Ready** | 11–12 | AI agents contribute like your best team members |
+
+
+## Step 0 — Detect GitHub context
+
+**Zero user input required.** Discover everything from GitHub's tools.
+
+### 0a. Identify the repo
+
+Run `git remote -v` to extract the GitHub `owner/repo`. If not GitHub, fall back to local-only analysis.
+
+### 0b–0d. Fetch metadata, mine PR reviews, check community health
+
+Use GitHub MCP tools or `gh` CLI to auto-discover repo metadata, PR review patterns, and community health gaps. See [references/github-discovery.md](references/github-discovery.md).
+
+Key insight: **PR review mining is the highest-value step.** Repeated reviewer feedback becomes conventions in `copilot-instructions.md`.
+
+
+## Step 1 — Analyze the codebase
+
+GitHub context tells you *what* the repo is. Local analysis tells you *how* it works.
+
+### 1a. Detect languages, frameworks, and repo type
+
+Find manifest files and extract details. See [references/detection-tables.md](references/detection-tables.md) for manifest tables, VS Code extension detection, multi-app collections, demo apps, and course repo heuristics.
+
+**Course repos** (3+ signals: numbered folders, lesson keywords, no primary app) adapt Steps 2–5.
+
+### 1b. Detect test setup
+
+Identify test runner, find test directories (`tests/`, `__tests__/`, `spec/`, `e2e/`), extract test commands from scripts.
+
+### 1c. Detect CI/CD
+
+Check `.github/workflows/` for PR triggers. Check for other CI systems. Recognize community workflows (stale, welcome) as valid automation — not missing CI.
+
+### 1d. Check existing AI configuration
+
+Check for: `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/skills/`, `.claude/skills/`, `.agents/skills/`, `.github/agents/`, `.github/extensions/`, `.devcontainer/`.
+
+**copilot-setup-steps.yml** — check ALL locations: `.github/workflows/` (canonical), `.github/` (legacy), repo root. If found outside `.github/workflows/`, flag for consolidation.
+
+If multiple instruction files exist, check for duplicates, contradictions, and drift. See [references/detection-tables.md](references/detection-tables.md).
+
+### 1e. Check repo configuration
+
+Check for: `CODEOWNERS`, `dependabot.yml`, issue templates, PR template, `LICENSE`, README Contributing section.
+
+### 1f–1g. Evaluate changelog and documentation
+
+Assess changelog health (exists, format, freshness). Assess docs (exists, framework, navigation, deploy pipeline, README linkage).
+
+### 1h. Scan directory structure
+
+List top-level directories and immediate children (skip `node_modules`, `.git`, `dist`, `build`, `target`, `vendor`).
+
+### 1i. Compile findings
+
+Produce a structured findings table combining GitHub context and codebase analysis with file-path evidence. List which of the 12 assets are missing; flag drift on existing ones. See [references/detection-tables.md](references/detection-tables.md) for the template.
+
+### 1j. Detect monorepo areas
+
+If workspace config found, list areas with name, path glob, and primary stack. For large library monorepos, map cross-package dependencies.
+
+
+## Step 2 — Generate AGENTS.md
+
+If missing, create `AGENTS.md` at the repo root. If it exists, compare against analysis and flag drift. **Do not overwrite.**
+
+Sections: Project Overview (never hardcode versions — reference manifests), Repository Structure, Tech Stack, Build & Run, Testing, Key Patterns and Conventions, CI/CD, Adding a New [Feature/Module] (trace the full registration chain — enums, index re-exports, config declarations), Screen Size / Responsive Rules (UI projects only), Common Pitfalls.
+
+
+## Step 3 — Generate AI convention files (copilot-instructions.md and/or CLAUDE.md)
+
+Generate shared conventions content **once**, then write to whichever files apply:
+
+- `.github/copilot-instructions.md` — read by every Copilot surface.
+- `CLAUDE.md` at repo root — read by Claude Code at session start.
+
+Default to generating **both**. If the user's prompt names one agent only, generate only that file. If one exists and the other doesn't, offer to create the missing one with the same content; flag drift if they've diverged.
+
+Content: Language-Specific Conventions, Notebook Conventions (if `.ipynb`), Course/Lesson Conventions (if course repo), Framework Patterns, Conventions Mined from PR Reviews, Test Conventions, Code Style Notes, Asset/Content Rules, **Maintenance Matrix** (trace dependency graphs — the most valuable section).
+
+**Monorepo:** Create `.github/instructions/{area-name}.instructions.md` with `applyTo` patterns for areas with different stacks (Copilot-specific — note monorepo areas directly in `CLAUDE.md` instead).
+
+
+## Step 4 — Generate copilot-setup-steps.yml
+
+Check ALL locations first: `.github/workflows/copilot-setup-steps.yml`, `.github/copilot-setup-steps.yml`, repo root. If one exists, consolidate into `.github/workflows/` if needed — do not duplicate.
+
+If truly missing, create `.github/workflows/copilot-setup-steps.yml`. Steps: checkout, set up runtime, install dependencies, build. Derive from existing CI. For .NET multi-target, install all required SDK versions.
+
+
+## Step 4b — Generate .mcp.json
+
+If missing, generate `.mcp.json` at the repo root based on detected dependencies (databases, APIs, cloud platforms, browser automation, DevOps tools). Use `${VAR}` for secrets. Only include servers the project needs.
+
+If `.vscode/mcp.json` exists, flag as "Could Be Better" and suggest migrating to `.mcp.json`.
+
+
+## Step 5 — Generate CI workflow
+
+If no PR-triggered workflow exists, create `.github/workflows/ci.yml` with `pull_request` + `push` triggers, `paths-ignore` for docs/config, and a build-and-test job matching the project's toolchain. Use the **default branch** from Step 0b. Do not modify existing workflows.
+
+
+## Step 6 — Generate issue templates and PR template
+
+If missing, create bug report and feature request YAML forms, plus a PR template with description, changes, how-to-test, and checklist (derived from maintenance matrix). Note old-format `.md` templates as "Could Be Better."
+
+
+## Step 7 — Update README Contributing section
+
+If README exists but has no Contributing section: link to `CONTRIBUTING.md` if it exists, otherwise add a Contributing section with fork/branch/PR instructions and test commands. Do not rewrite the rest of the README.
+
+
+## Step 8 — Verify maintenance matrix
+
+Verify the matrix covers file cross-references, change cascades, and cross-cutting concerns. Trace actual dependency graphs (`.csproj` ProjectReferences, import chains, `mod` declarations, `__init__.py` re-exports).
+
+
+## Step 9 — Evaluate and improve changelog
+
+If missing, create `CHANGELOG.md` with Keep a Changelog format. If a pointer file, verify the target. If stale, flag with dates. Document non-standard locations in AGENTS.md.
+
+
+## Step 10 — Evaluate and improve documentation
+
+If docs exist, add to AGENTS.md and copilot-instructions.md/CLAUDE.md. If missing, assess whether needed by project type. Always document docs status in AGENTS.md.
+
+
+## Step 11 — Display the AI-Readiness Report
+
+Display the report using [references/report-template.md](references/report-template.md). Include the skill version from frontmatter `metadata.version`. Then:
+1. Add AI-Ready badge (§ 11a)
+2. Offer to create PR (§ 11b)
+
+
+## Important Rules
+
+### Do No Harm
+
+Leave the repo in a **better state than you found it**.
+
+- **No duplicates** — check ALL known locations before creating any file. Consolidate instead.
+- **No direct pushes to main/master** — feature branch + PR. Exception: user explicitly asks.
+- **No overwrites** — create missing assets only. Flag drift for user review.
+- **No deletions without approval** — include deletions in the PR for review.
+
+### General Rules
+
+- **No pagers** — append `| cat` to `gh`/`git` commands. Use `git --no-pager`.
+- **Customize to the repo's actual stack** — no generic boilerplate.
+- **Self-consistency** — generated files must follow the conventions you establish.
+- **GitHub-native** — auto-discover via MCP tools and `gh` CLI. Fall back to local analysis.
+- **Mine PR reviews** — repeated review feedback becomes `copilot-instructions.md`/`CLAUDE.md` rules.
+- **Be specific** — real file paths, real commands, real patterns.
+- **Create new files directly** — no incremental edits.
+- **Run full analysis first (Steps 0–1)** — no guessing.
+- **Display the report at the end** — no skipping or abbreviating.
+- **No markdown headings in conversational user output** — use bold + emojis. Headings are allowed in generated files and in the consolidated PR comment report defined in [references/report-template.md](references/report-template.md).
+- **Attribute the AI Ready skill** — include `Assisted by [ai-ready](https://github.com/johnpapa/ai-ready)` in issue/PR communication.
+- **Update docs to repo standards** — keep `README.md`, `docs/how-it-works.md`, `AGENTS.md`, `CHANGELOG.md` in sync.
+- **Handle PR conflicts proactively** — sync with target branch, attempt resolution, ask user if stuck.
+
+
+## Training Repos
+
+See [references/training-repos.md](references/training-repos.md) for the full list of repos used to validate this skill's heuristics.