# AI Ready > Analyzes repositories for AI agent development efficiency. Scores 8 aspects (documentation, architecture, testing, type safety, agent instructions, file structure, context optimization, security) with ASCII dashboards. Use when evaluating AI-readiness, preparing codebases for Claude Code, or improving repository structure for AI-assisted development. - Skill: `viktor-silakov/ai-ready` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds@latest add viktor-silakov/ai-ready` - Raw SKILL.md: https://api.skillmd.com/api/skills/viktor-silakov/ai-ready/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: viktor-silakov (https://skillmd.com/u/viktor-silakov) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/viktor-silakov/ai-ready --- # AI-Readiness Analysis Evaluate repository readiness for AI-assisted development across 8 weighted aspects. ## Workflow Checklist Copy and track progress: ``` AI-Readiness Analysis Progress: - [ ] Step 1: Discover repository - [ ] Step 2: Gather user context (Q1-Q4) - [ ] Step 3: Analyze 8 aspects - [ ] Step 4: Calculate scores and grade - [ ] Step 5: Display ASCII dashboard - [ ] Step 6: Present issues by severity - [ ] Step 7: Priority survey (Q5-Q9) - [ ] Step 8: Enter plan mode - [ ] Step 9: Create phased roadmap - [ ] Step 10: Generate templates - [ ] Step 11: Save reports to .aiready/ (confirm HTML generation) - [ ] Step 12: Ask to open HTML report ``` --- ## Step 1: Repository Discovery ``` Target: {argument OR cwd} ``` Discover: 1. **Language/Framework:** Check package.json, Cargo.toml, go.mod, pyproject.toml 2. **History:** Check `.aiready/history/index.json` for delta tracking 3. **Agent files:** CLAUDE.md, AGENTS.md, .cursorrules, copilot-instructions.md --- ## Step 2: Context Gathering Use AskUserQuestion with these 4 questions: | Q | Question | Options | |---|----------|---------| | Q1 | Rework depth? | Quick Wins / Medium / Deep Refactor | | Q2 | Timeline? | Urgent / Planned / Strategic / Continuous | | Q3 | Team size? | Solo / Small (2-5) / Large (5+) / Open Source | | Q4 | AI tools used? | Claude Code / Copilot / Cursor / Windsurf / Aider (multiselect) | Store responses for Steps 6 and 11. --- ## Step 3: Analyze 8 Aspects Evaluate each criterion 0-5-10. See **[criteria/aspects.md](criteria/aspects.md)** for full rubrics. | Aspect | Weight | Criteria | |--------|--------|----------| | Documentation | 15% | 19 | | Architecture | 15% | 18 | | Testing | 12% | 23 | | Type Safety | 12% | 10 | | Agent Instructions | 15% | 25 | | File Structure | 10% | 13 | | Context Optimization | 11% | 20 | | Security | 10% | 12 | --- ## Step 4: Calculate Scores ``` Aspect Score = (Sum of criteria / Max points) × 100 Overall = (Doc × 0.15) + (Arch × 0.15) + (Test × 0.12) + (Type × 0.12) + (Agent × 0.15) + (File × 0.10) + (Context × 0.11) + (Security × 0.10) ``` | Grade | Range | |-------|-------| | A | 90-100 | | B | 75-89 | | C | 60-74 | | D | 45-59 | | F | 0-44 | --- ## Step 5: Display Dashboard ``` ╔══════════════════════════════════════════════════════════════════════════════╗ ║ AI-READINESS REPORT ║ ║ Repository: {name} | Language: {lang} | Framework: {fw} ║ ╠══════════════════════════════════════════════════════════════════════════════╣ ║ OVERALL GRADE: {X} SCORE: {XX}/100 {delta} ║ ╠══════════════════════════════════════════════════════════════════════════════╣ ║ 1. Documentation {bar} {score}/100 {delta} ║ ║ 2. Architecture {bar} {score}/100 {delta} ║ ║ 3. Testing {bar} {score}/100 {delta} ║ ║ 4. Type Safety {bar} {score}/100 {delta} ║ ║ 5. Agent Instructions {bar} {score}/100 {delta} ║ ║ 6. File Structure {bar} {score}/100 {delta} ║ ║ 7. Context Optimization{bar} {score}/100 {delta} ║ ║ 8. Security {bar} {score}/100 {delta} ║ ╚══════════════════════════════════════════════════════════════════════════════╝ ``` **Progress bars:** `████████░░` = 80/100 (█ filled, ░ empty, 10 chars total) **Deltas:** `↑+N` improvement | `↓-N` decline | `→0` unchanged | `(new)` first run **Issue Summary Block:** ``` ╔══════════════════════════════════════════════════════════════════════════════╗ ║ ISSUE SUMMARY ║ ╠══════════════════════════════════════════════════════════════════════════════╣ ║ 🔴 CRITICAL {bar} {N} ║ ║ 🟡 WARNING {bar} {N} ║ ║ 🔵 INFO {bar} {N} ║ ║ Distribution by Aspect: (sorted by issue count) ║ ╚══════════════════════════════════════════════════════════════════════════════╝ ``` If history exists, show **Progress Over Time** chart with trend analysis. --- ## Step 6: Present Issues Group by severity, then aspect. See **[reference/severity.md](reference/severity.md)** for classification. ``` 🔴 CRITICAL ({N}) ────────────────────────────────────────────────────────────────────── [C1] {Aspect}: {Issue} Impact: {description} Effort: Low/Medium/High 🟡 WARNING ({N}) ────────────────────────────────────────────────────────────────────── [W1] {Aspect}: {Issue} Impact: {description} ``` --- ## Step 7: Priority Survey Use AskUserQuestion for prioritization: | Q | Question | Purpose | |---|----------|---------| | Q5 | Priority areas (top 3)? | Focus recommendations | | Q6 | Critical issue order? | Prioritize fixes | | Q7 | Which warnings to fix? | Scope work | | Q8 | Constraints? | Legacy code, compliance, CI/CD | | Q9 | Success metrics? | Target grade, zero critical | **Filter by rework depth from Q1:** - Quick Wins → Phase 1 only - Medium → Phases 1-2 - Deep → All phases --- ## Step 8: Enter Plan Mode After survey, use EnterPlanMode tool. --- ## Step 9: Phased Roadmap | Phase | Focus | Examples | |-------|-------|----------| | 1: Quick Wins | File creation, config | CLAUDE.md, .aiignore, llms.txt | | 2: Foundation | Structural changes | ARCHITECTURE.md, file splitting, types | | 3: Advanced | Deep improvements | Coverage >80%, ADRs, architecture enforcement | --- ## Step 10: Generate Templates For selected issues, generate from templates: - **CLAUDE.md:** See **[templates/CLAUDE.md.template](templates/CLAUDE.md.template)** - **ARCHITECTURE.md:** See **[templates/ARCHITECTURE.md.template](templates/ARCHITECTURE.md.template)** --- ## Step 11: Save Reports Before writing the HTML file, always ask the user: ``` AskUserQuestion: Question: "Generate HTML report now?" Options: ["Yes, generate HTML", "No, skip HTML"] ``` If "Yes", create the HTML report. If "No", skip HTML but still write Markdown/JSON. Save to `.aiready/history/reports/` with timestamp: ``` .aiready/ ├── config.json # User preferences ├── history/ │ ├── index.json # Report index for delta tracking │ └── reports/ │ ├── {YYYY-MM-DD}_{HHMMSS}.md │ ├── {YYYY-MM-DD}_{HHMMSS}.html │ └── {YYYY-MM-DD}_{HHMMSS}.json ``` **Markdown report:** Scores, issues, recommendations, user context **HTML dashboard:** See **[templates/report.html](templates/report.html)** **JSON data:** Raw scores for delta tracking Update `index.json` with new report entry and trend analysis. ### Open Report If the HTML report was generated and saved, immediately ask: ``` AskUserQuestion: Question: "Open HTML report in browser?" Options: ["Yes, open report", "No, skip"] ``` If HTML was skipped, do not prompt to open. If yes, run: ```bash open .aiready/history/reports/{timestamp}.html ``` --- ## Validation Loop After each major step, verify: 1. **After analysis:** All 8 aspects scored? 2. **After issues:** Severity correctly classified? 3. **After survey:** User selections captured? 4. **After templates:** Files properly generated? 5. **After save:** Reports written to .aiready/? If validation fails, return to the failed step. --- ## Quick Reference | File | Content | |------|---------| | [criteria/aspects.md](criteria/aspects.md) | Full scoring rubrics for all 8 aspects | | [reference/severity.md](reference/severity.md) | Issue severity classification | | [templates/CLAUDE.md.template](templates/CLAUDE.md.template) | Agent instructions template | | [templates/ARCHITECTURE.md.template](templates/ARCHITECTURE.md.template) | Architecture doc template | | [templates/report.html](templates/report.html) | HTML dashboard template | | [examples/](examples/) | Example reports |