ai-ready
Skill1.2k starsChanged 2 months agoMITView on GitHub
**ANALYSIS SKILL** — Analyze any repository and generate AI-ready configuration — AGENTS.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: glob, grep, view, create, edit for repo analysis and file generation. FOR SINGLE OPERATIONS: use create/edit directly for individual config files.
9 other projects use a version of this, 3 of them edited.
Trending
More talk lately.about the whole repository
Most recently taken up by
- taixuann/development-spacetheir own version, first seen Nov 8, 2026
- MarieLynneBlock/arcanum-artifextheir own version, first seen Nov 1, 2026
- Agentic-Chat-Rooms-Protocol/acr-mcp-serveredited, first seen Nov 1, 2026
- github/awesome-copilottheir own version, first seen Oct 25, 2026
- flightctl/ai-workflowstheir own version, first seen Oct 22, 2026
- kargnas/skillstheir own version, first seen Oct 18, 2026
Who's talking about johnpapa/vscode-peacock
- microsoft/vscode-remote-release“Remote: Iteration Plan for July 2019”GitHub · Jul 5, 2019 · 7 reactions
- A Hacker News story“Visual Studio Code: Peacock”Hacker News · May 3, 2021 · 4 points
- forem/forem“Embed GitHub Code”GitHub · Mar 12, 2019 · 4 reactions
- @hejchristian.com“Desperately needed to install this Peacock extension today, as I find myself with three different projects …”Bluesky · Mar 21, 2026 · 2 likes
- zed-industries/zed“Allow per-project (worktree) theme overrides for Peacock-style window tinting”GitHub · May 20, 2026 · 1 reactions
The biggest 5 of 18 mentions linking to the repository that our crawl found. Each line is their own headline.
See all 18
Talked about on GitHub, Hacker News, Bluesky and Stack Overflow (18 times).
On GitHub · 15
- Jul 5, 2019Remote: Iteration Plan for July 2019 — microsoft/vscode-remote-release7 reactions
- Mar 12, 2019Embed GitHub Code — forem/forem4 reactions · 16 comments
- May 20, 2026Allow per-project (worktree) theme overrides for Peacock-style window tinting — zed-industries/zed1 reaction
- Oct 31, 2019Improve Onboarding — Kruemelkatze/vscode-dashboard1 reaction · 6 comments
- Oct 23, 2026Multiple BOBs when more than 1 window is open — EricKhmel/BobPet0 reactions
10 more on GitHub
- Sep 17, 2026Modern UI doesn't work with Peacock extension — posit-dev/positron0 reactions · 3 comments
- Aug 4, 2026ModernUI breaks custom theming — bojordan/ColorIdentity0 reactions
- Mar 21, 2026feat: Kunterbunt – automated workspace color extension for VS Code — martinus/vsode-extension-kunterbunt0 reactions
- Sep 13, 2023Add Code of conduct — thoroc/projen-typescript-git-hooks0 reactions
- Apr 19, 2023devcontainer creation fails when project is empty — microsoft/vscode-remote-release0 reactions · 2 comments
- Sep 22, 2020Peacock — coder/code-server0 reactions · 2 comments
- Nov 29, 2019Reach out to extensions to adopt new extension kind behaviour — microsoft/vscode0 reactions · 1 comment
- Nov 2, 2019https://github.com/johnpapa/vscode-peacock/commits — johnpapa/express-to-functions0 reactions · 2 comments
- Apr 30, 2019Integrate GitHub dependabot — SAP/spartacus0 reactions · 3 comments
- Mar 15, 2019Change Title Bar Color on Pair Swap — FordLabs/pairodoro0 reactions · 1 comment
On Hacker News · 1
- May 3, 2021Visual Studio Code: Peacock4 points
On Bluesky · 1
- Mar 21, 2026Desperately needed to install this Peacock extension today, as I find myself with three different projects open and no way to distinguish… — @hejchristian.com2 likes and reposts · 2 replies
On Stack Overflow · 1
- Dec 7, 2020VSCode different Theme setting for each project in a WorkSpace1 vote
Other versions9 projects use a version of this.
Word for word · 0
None found.
Edited · 3
- johnpapa/ai-ready★ 21931% same
- Agentic-Chat-Rooms-Protocol/acr-mcp-server★ 069% same
- VRIL-LABS/ai-ready-universal★ 069% same
Wrote their own version · 6
- github/awesome-copilot★ 41ksame name
- flightctl/ai-workflows★ 10same name
- kargnas/skills★ 9same name
- MarieLynneBlock/arcanum-artifex★ 4same name
- taixuann/development-space★ 1same name
- yejuntak/hcai-deployment-readiness★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository2 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
The file
Show its rules and text
We split this skill into the rules it gives an agent
23 rules. 0 are common, 9 are distinctive, and 14 are very specific to this project.
0
Common
Most of the 9 edited versions we read keep these.
9
Distinctive
This author's own choices. Worth a look.
14
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 17
Follow these steps in order to analyze the current repository and generate all missing AI-ready configuration assets.
- Distinctive: line 21
Skipping assets: If the user's prompt mentions skipping specific assets (e.g., "skip CI and issue templates"), respect those exclusions.
- Distinctive: line 23
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 …
- Very specific: line 73
Run git remote -v to extract the GitHub owner/repo.
- Very specific: line 77
Use GitHub MCP tools or gh CLI to auto-discover repo metadata, PR review patterns, and community health gaps.
- Very specific: line 101
Check .github/workflows/ for PR triggers.
- Very specific: line 105
Check for: AGENTS.md, .github/copilot-instructions.md, .github/skills/, .github/agents/, .github/extensions/, .devcontainer/.
- Distinctive: line 109
If multiple instruction files exist, check for duplicates, contradictions, stale references, and scope clarity.
- Very specific: line 113
Check for: CODEOWNERS, dependabot.yml, issue templates, PR template, LICENSE, README Contributing section.
- Distinctive: line 131
If workspace config found, list areas with name, path glob, and primary stack.
- Distinctive: line 137
If missing, create AGENTS.md at the repo root.
- Distinctive: line 145
If missing, create it. If it exists, compare against analysis — especially new PR review patterns and maintenance matrix drift.
- Very specific: line 151
Monorepo: Create .github/instructions/{area-name}.instructions.md with applyTo patterns for areas with different stacks.
- Very specific: line 157
Check ALL locations first: .github/workflows/copilot-setup-steps.yml, .github/copilot-setup-steps.yml, and repo root.
- Very specific: line 159
If truly missing from all locations, create .github/workflows/copilot-setup-steps.yml.
- Very specific: line 165
If missing, generate .mcp.json at the repo root based on detected dependencies (databases, APIs, cloud platforms, browser automation, …
- Very specific: line 173
If no PR-triggered workflow exists, create .github/workflows/ci.yml with: pull_request + push triggers with paths-ignore for docs/config, a …
- Very specific: line 179
If missing, create bug report and feature request YAML forms, plus a PR template with description, changes, how-to-test, and checklist …
- Very specific: line 185
If README exists but has no Contributing section: link to CONTRIBUTING.md if it exists, otherwise add a Contributing section with …
- Very specific: line 191
Verify the matrix in copilot-instructions.md covers file cross-references, change cascades, and cross-cutting concerns.
- Very specific: line 197
If missing, create CHANGELOG.md with Keep a Changelog format.
- Distinctive: line 203
If docs exist, add to AGENTS.md and copilot-instructions.md.
- Distinctive: line 210
Add AI-Ready badge (see report-template.md § 11a)
“Common” is measured: kept by at least 6 in 10 of the 9 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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 | Step 3 |
| 3 | Maintenance matrix (in copilot-instructions.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 automatically
Zero user input required. The skill is GitHub-native — it discovers 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 for the full API table, PR mining technique, and health gap mapping.
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. Use glob, grep, and view combined with GitHub context from Step 0.
1a. Detect languages, frameworks, and repo type
Find manifest files and extract details. See references/detection-tables.md for the full manifest table, VS Code extension detection, multi-app collections, demo app patterns, and course/tutorial repo detection.
Key detections: lockfiles, runtime version files, monorepo markers, notebooks, VS Code extensions, multi-app collections, demo apps.
Course repos (3+ signals: numbered folders, lesson keywords, no primary app) adapt Steps 2–5. See detection-tables.md for the full signal list and step adaptations.
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, .github/copilot-instructions.md, .github/skills/, .github/agents/, .github/extensions/, .devcontainer/.
copilot-setup-steps.yml — check ALL known locations: .github/workflows/copilot-setup-steps.yml (canonical), .github/copilot-setup-steps.yml (legacy), and repo root. If found in a non-canonical location, flag it for consolidation into .github/workflows/ — do not create a duplicate.
If multiple instruction files exist, check for duplicates, contradictions, stale references, and scope clarity. See references/detection-tables.md for drift detection details.
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. See references/detection-tables.md for the full findings table template.
List which of the 12 assets are missing. For existing assets, compare against analysis and flag drift as "Could Be Better."
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. See references/detection-tables.md for details.
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 .github/copilot-instructions.md
If missing, create it. If it exists, compare against analysis — especially new PR review patterns and maintenance matrix drift.
Content: Language-Specific Conventions (separate subsections for multi-language repos), Notebook Conventions (if .ipynb detected), Course/Lesson Conventions (if course repo), Framework Patterns, Conventions Mined from PR Reviews, Test Conventions, Code Style Notes (reference linter configs), Asset/Content Rules (if assets detected), Maintenance Matrix (trace dependency graphs — the most valuable section).
The maintenance matrix defines what must be updated when different parts of the codebase change. Populate with real file paths. Trace import chains and registration patterns — don't stop at top-level files.
Monorepo: Create .github/instructions/{area-name}.instructions.md with applyTo patterns for areas with different stacks.
Step 4 — Generate copilot-setup-steps.yml
Check ALL locations first: .github/workflows/copilot-setup-steps.yml, .github/copilot-setup-steps.yml, and repo root. If one exists anywhere, do NOT create another — consolidate into .github/workflows/ if at a legacy location.
If truly missing from all locations, create .github/workflows/copilot-setup-steps.yml. Steps: checkout, set up runtime, install dependencies, install test dependencies, build. Derive from existing CI when possible. 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 actually needs — do not speculatively add servers.
Why?: Copilot CLI no longer supports .vscode/mcp.json — the correct location is .mcp.json at the repo root. If .vscode/mcp.json exists, flag it 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 with paths-ignore for docs/config, a build-and-test job matching the project's actual toolchain. Use the default branch detected in Step 0b — do not hardcode main. Never 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. Never rewrite the rest of the README.
Step 8 — Verify maintenance matrix
Verify the matrix in copilot-instructions.md covers file cross-references, change cascades, and cross-cutting concerns. Trace actual dependency graphs per language (.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. 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 the format in references/report-template.md. Include the skill version from frontmatter metadata.version at the bottom of the report (e.g., Assisted by ai-ready v1.0.0). Then:
- Add AI-Ready badge (see report-template.md § 11a)
- Offer to create PR (see report-template.md § 11b)
Important Rules
Do No Harm
This skill's first obligation is to leave the repo in a better state than it found it — never worse. Every rule below serves this principle.
- NEVER create duplicates — before creating any file, check ALL known locations (canonical, legacy, and root). If a file exists anywhere, do not create another copy. Consolidate instead.
- NEVER push directly to main/master — always create a feature branch and open a PR for review. The only exception is if the user explicitly asks to commit to the default branch.
- NEVER leave an opened PR unattended — once a PR is open and CI passes, either merge it (small, well-tested, no ambiguous judgment calls) or ask the user which way to go; report the outcome either way. Opening a PR and going quiet is not acceptable. If CI is red or still pending, don't merge — fix it, wait, or report the blocker instead.
- Whenever a merge happens, use squash and delete the branch afterward — both local and remote. Don't leave merged branches lying around.
- NEVER overwrite existing files — only create missing assets. Flag drift for user review.
- NEVER delete files without user approval — if consolidating duplicates or removing stale files, include the deletion in the PR for review.
General Rules
- NEVER open a pager — append
| catto everygh/gitcommand. Usegit --no-pager. - ALWAYS customize to the repo's actual stack — never produce generic boilerplate.
- Self-consistency — every generated file must follow the conventions you establish. Cross-check before finalizing.
- GitHub-native by default — auto-discover via MCP tools and
ghCLI. Fall back to local analysis. - Mine PR reviews — turn repeated review feedback into
copilot-instructions.mdrules. - Be specific — real file paths, real commands, real patterns.
- Use
createto write new files — nevereditfrom scratch. - Run full analysis first (Steps 0–1) — never guess.
- ALWAYS display the report at the end — never skip or abbreviate.
- NEVER use markdown headings in user output — use bold + emojis instead.
- ALWAYS mention the AI Ready skill in issue/PR communication — when posting to an issue or PR (body or comment), include explicit attribution such as
Assisted by [ai-ready](https://github.com/johnpapa/ai-ready). - ALWAYS update docs to repo standards — when generated guidance or workflows change, update related docs and changelog per the repo's maintenance matrix (for this repo:
README.md,docs/how-it-works.md,AGENTS.md,CHANGELOG.md). - ALWAYS handle PR conflicts proactively — when creating PRs, sync with the target branch and attempt conflict resolution; if conflicts remain, explicitly ask the user how they want to proceed.
Training Repos
See references/training-repos.md for the full list of repos used to validate this skill's heuristics.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

