Skip to content

johnpapa/ai-ready

v1.3.0MIT

Analyze any repository and generate AI-ready configuration — AGENTS.md, copilot-instructions.md, skills, CI workflows, issue templates.

GitHubOpen Website

Changelog

All notable changes to this project will be documented in this file.

[Unreleased]

Changed

  • Copilot install now uses the marketplace — documented copilot plugin install ai-ready@awesome-copilot instead of installing straight from the repo. Copilot CLI reports direct repo, URL, and local-path installs as deprecated.

Fixed

  • Docs-only PRs could never merge — validate is a required status check, but the CI workflow's pull_request trigger used paths-ignore for markdown. A PR touching only docs never ran the check, so branch protection blocked it forever. Removed paths-ignore from the pull_request trigger; the job takes about ten seconds.

[1.3.0] — 2026-09-05

Added

  • Multi-tool support — the skill now installs in Claude Code, OpenAI Codex, and Cursor in addition to GitHub Copilot, via the vendor-neutral Agent Skills standard. Added .claude-plugin/plugin.json, .claude-plugin/marketplace.json, .codex-plugin/plugin.json, and an Agent Plugins plugin.json at the repo root. All manifests point at the same canonical skills/ai-ready/ — no content is duplicated.

  • npx skills add johnpapa/ai-ready — documented as the primary install path. The open skills CLI reads the standard skills/<name>/SKILL.md layout and installs into 70+ agents, so no bespoke installer is needed. Added skills.sh.json so the repo renders correctly on the skills.sh registry.

  • Install troubleshooting — README now covers the three failure modes users actually hit: the agent not picking up the skill, SHA-vs-tag marketplace clone errors, and Claude marketplace SSH auth failures.

Fixed

  • Incomplete Codex install instructions — the documented Codex path registered the marketplace but never installed the plugin. Added the required second command, codex plugin add ai-ready@johnpapa-ai-ready.
  • Wrong Codex invocation syntax — Codex CLI mentions skills with $ai-ready, not /ai-ready. Documented the correct prefix per tool.
  • Skill not discovered outside GitHub Copilot — the repo previously shipped only a Copilot plugin manifest, so Claude Code, Codex, and Cursor had nothing to discover and never invoked the skill.
  • Marketplace install metadata — aligned .github/plugin/plugin.json with the released 1.2.0 skill version and added a CI check that fails when the plugin manifest version drifts from skills/ai-ready/SKILL.md. Marketplace refs should use a release tag such as v1.2.0, not a commit SHA. (Fixes #26)

Changed

  • Documentation sync rule — when skill behavior changes, update related docs to match repo standards and maintenance matrix.
  • PR conflict handling rule — when preparing PRs, sync with the target branch and attempt conflict resolution; if conflicts remain, ask the user how to proceed.
  • PR follow-through rule — the never-push-to-main rule now covers what happens after a PR is opened too: once CI passes, merge it (if low-risk and well-tested) or ask the user, and always report the outcome. An opened PR left unattended, with no report back, is no longer acceptable.
  • Squash + delete-branch rule — whenever a merge happens, use squash and delete the branch afterward (local and remote).

[1.2.0] — 2026-07-17

Changed

  • PR comment etiquette in report flow — Step 11b guidance now requires a single consolidated PR report comment (including immediate clarifications) and advises updating that same comment instead of posting serial clarification comments.
  • Issue/PR attribution rule — every issue comment, PR comment, and PR body update produced by the skill must explicitly mention AI Ready (for example: Assisted by [ai-ready](https://github.com/johnpapa/ai-ready)).
  • Attribution phrasing — changed from "Generated by" to "Assisted by" throughout report footers and comment templates.

[1.1.0] — 2026-05-19

Added

  • Plugin manifest (.github/plugin/plugin.json) — enables installation via copilot plugin install johnpapa/ai-ready from the terminal. Submitted as external plugin to awesome-copilot marketplace (issue #1750).

Fixed

  • MCP config path — changed from .vscode/mcp.json to .mcp.json at repo root (Copilot CLI dropped .vscode/mcp.json support). Existing .vscode/mcp.json files are now flagged for migration. (Fixes #24)
  • Install instructions — fixed install command to use copilot plugin install johnpapa/ai-ready. (Fixes #23)

Changed

  • CI workflow — added paths-ignore to skip runs on docs-only changes

[1.0.0] — 2026-05-15

Changed

  • SKILL.md refactored for Agent Skills spec compliance — split from 964 lines / ~15,800 tokens to 225 lines / ~2,800 tokens with progressive disclosure via references/ directory
  • Frontmatter improved — added license: MIT, metadata.version: 1.0.0, WHEN: trigger phrases, INVOKES:, FOR SINGLE OPERATIONS:, ANALYSIS SKILL prefix (sensei High score)
  • Version displayed in report output — report now shows Assisted by ai-ready v1.0.0
  • Install instructions — primary install method is now gh skills install johnpapa/ai-ready ai-ready --scope user
  • All references to "plugin" updated to "skill" across README, AGENTS.md, copilot-instructions.md, CI, issue templates, PR template, SECURITY.md, and docs
  • Writing style pass — added Why? explanations throughout SKILL.md for key decisions and rules, matching John Papa's Angular Style Guide voice
  • Interactive post-report flow — instead of telling users to copy-paste commands, the skill now asks directly: "Would you like me to create a branch and open a PR?"
  • PR creation changed from draft PR to regular PR
  • Pager prevention — all gh and git commands now mandate | cat or --no-pager to prevent hanging sessions
  • PR review mining (Step 0c) — expands search to 20 PRs if initial batch has no review comments, and notes when no patterns are found
  • Topic addition (Step 11b) — checks push permissions before attempting gh repo edit; skips silently if no access
  • Setup steps (Step 4) — now derives from existing CI workflow as source of truth for SDK versions and build commands
  • README Contributing (Step 7) — if standalone CONTRIBUTING.md exists, links to it instead of duplicating content
  • Issue templates (Step 6) — flags old-format markdown templates as "Could Be Better" with migration suggestion
  • CI workflow (Step 5) — uses detected default branch instead of hardcoding main
  • Contributors row rationale changed from "who to put in CODEOWNERS" to "contribution patterns" — CODEOWNERS is a human reviewer workflow, not an AI-readiness concern
  • Skill now has 12 steps (was 11)

Added

  • skills/ai-ready/references/ directory with 4 reference files:
    • github-discovery.md — GitHub API tables, PR mining, health gap mapping
    • detection-tables.md — manifest/course/monorepo detection heuristics
    • report-template.md — report format, HTML spec, badge, PR flow
    • training-repos.md — validation repo list
  • "Tested Against" section in README linking to training repos
  • references/* entry in maintenance matrix
  • "Do No Harm" principle — safety rules: never create duplicates, never push to main/master without permission, never overwrite files, never delete without approval
  • Duplicate file prevention — Step 1d and Step 4 check ALL known locations for copilot-setup-steps.yml before creating
  • Updated CHANGELOG.md checkbox added to PR template checklist
  • Course repo detection (Step 1a-ii) — multi-signal detection (numbered folders + README language + topics + lesson structure + no root manifest) to identify course/tutorial repos and adapt generation accordingly
  • Notebook awareness (Step 1a) — detects .ipynb files and generates notebook conventions (clear outputs, pin kernel, focused cells)
  • Multi-language support (Step 3) — repos with no dominant language get per-language convention sections instead of one blended block
  • Community workflow recognition (Step 1c) — welcome/stale/lock workflows are recognized as valid automation, not flagged as "missing CI"
  • Monorepo area support (Step 1j/3) — detects workspace areas and generates per-area .instructions.md files with applyTo glob patterns for scoped AI instructions
  • MCP server config generation (Step 4b) — generates .mcp.json based on detected database, API, and tool dependencies
  • HTML readiness reports (Step 11) — optional self-contained HTML report for sharing with stakeholders, triggered by user request
  • Instruction consistency checking (Step 1d) — detects contradictions, duplicates, and stale references across AGENTS.md, copilot-instructions.md, CLAUDE.md, and .instructions.md files
  • 4-level maturity model — repos earn a medal from 🥉 Getting Started to 🏆 AI-Ready based on weighted AI-readiness percentage
  • Weighted impact scoring — assets use a 3-tier weight system (High=3, Medium=2, Low=1), so copilot-instructions.md matters more than dependabot.yml
  • AI-Ready badge — opt-in Shields.io badge added to README, linking back to this skill for discoverability
  • Self-consistency rule — generated files must follow the conventions established in the same PR's copilot-instructions.md, so Copilot code review finds zero issues
  • Explicit asset list — the 12 tracked assets are now enumerated with a scoring rubric (Nailed It = 1, Could Be Better = 0.5, Missing = 0)
  • Pre-existing AI Config section in the report — repos with existing copilot-instructions.md, custom agents, or custom skills get a dedicated section acknowledging what's already there
  • Push permissions check (Step 0b) — detects whether the user can push directly or needs a fork
  • Fork-based PR workflow — when the user lacks push access, the skill automatically forks, pushes to the fork, and opens a cross-fork PR
  • Default branch detection — uses defaultBranchRef from GitHub API instead of assuming main
  • Custom agents/skills enumeration (Step 1d) — lists and describes each agent/skill found in .github/agents/ and .github/skills/
  • Maintenance matrix import chain guidance — language-specific techniques for tracing dependency graphs (.NET, Node.js, Go, Python, Rust)
  • Multi-target .NET support (Step 4) — detects <TargetFrameworks> in .csproj and ensures all SDK versions are in setup steps

Removed

  • Daily tip hook — removed sessionStart prompt hook and hooks/hooks.json
  • Daily tip skill — removed skills/daily-tip/SKILL.md
  • Plugin wrapper — removed .github/plugin/plugin.json; ai-ready is now a standalone skill, not a plugin

Fixed

  • Duplicate copilot-setup-steps.yml creation — previous runs could create a second copy if the file existed at a legacy location

[0.3.0-alpha] — 2026-04-24

Added

  • Made repo public (alpha release)
  • PR template with integrity checklist and "Tested On" table
  • CODEOWNERS (@johnpapa)
  • Alpha banner in README
  • GitHub repo topics and description
  • CHANGELOG.md, SECURITY.md, dependabot.yml
  • Changelog evaluation (Step 1f/9) — detects changelog location (root, docs, releases), follows pointer files, checks freshness against git tags, assesses format
  • Documentation evaluation (Step 1g/10) — detects docs framework (Docsify, Docusaurus, MkDocs, etc.), checks nav/TOC, deploy pipeline, README linkage, assesses whether docs are needed
  • Expanded analysis findings table with changelog and docs rows

Changed

  • Skill now has 11 steps (was 9)
  • Bumped version to 0.3.0-alpha
  • Updated docs/how-it-works.md with steps 10-11

[0.2.0] — 2026-04-24

Changed

  • Removed custom extension (extension.mjs) — plugin system doesn't load extensions
  • Rewrote SKILL.md Step 1 to use built-in tools (glob, grep, view) with structured analysis schema
  • Skill is now fully self-sufficient — no custom tools required

Added

  • AGENTS.md — contributor guide for this repo
  • .github/copilot-instructions.md — conventions + maintenance matrix
  • .github/workflows/copilot-setup-steps.yml — checkout-only setup
  • .github/workflows/ci.yml — plugin integrity validation
  • Issue templates (bug report, feature request, new skill idea)
  • README Contributing section with smoke test guide

Removed

  • extensions/ai-ready-repo/extension.mjs — replaced by skill-native analysis

[0.1.0] — 2026-04-23

Added

  • Initial plugin: skill, extension, docs, and README
  • Plugin manifest (plugin.json) for copilot plugin install
  • 9-step skill procedure (SKILL.md)
  • analyze_repo_for_ai_readiness extension tool
  • Documentation: README, docs/how-it-works.md
  • MIT License