Summary
Analyze a codebase to identify gaps, inconsistencies, and friction points that would hinder autonomous agents (or developers) from effectively understanding, modifying, and extending the project. Provide concrete, prioritized recommendations to improve agent operability.
When to use
- You need a readiness audit before introducing autonomous agents to a repository.
- Developer onboarding is slow due to unclear architecture or weak conventions.
- The team needs prioritized fixes that improve codebase navigability and change safety.
When not to use
- The request is a narrow bug hunt or compiler-error triage.
- The goal is implementation of a specific feature rather than readiness assessment.
- The repository scope is too partial to assess structure and conventions reliably.
Inputs
- Project files (full or partial repository)
- Optional:
- Project guidelines / contributing docs - CI/CD configs - Issue tracker or roadmap - Target agent capabilities (e.g., codegen, refactor, test-writing) - Project-level agent metadata files (optional but recommended): checks for AGENTS.md, AGENTS.yaml, or CLAUDE.md that document agent entrypoints, permissions, or onboarding notes.
Outputs
Structured report with explicit, numbered sections and prioritized findings:
- Summary
- High-level assessment of agent readiness - Key risks and missing capabilities
- Gap Analysis
- Missing or unclear structure - Incomplete abstractions - Poor naming or discoverability - Hidden coupling / implicit behavior - Inconsistent patterns
- Agent Friction Points
- Areas where intent is unclear - Non-local reasoning required - Lack of type safety or contracts - Dynamic or implicit behavior - Missing or weak test coverage - Unclear side effects or state flow
- Documentation Deficiencies
- Missing high-level architecture overview - Missing module/service boundaries - Lack of “how to extend” guidance - Missing API or schema definitions
- Tooling & Automation Gaps
- Missing linting / formatting rules - Weak or absent CI checks - No type enforcement - Missing code generation or scaffolding tools
- Recommendations (Prioritized)
- Ordered by impact vs effort - Each includes: - Problem - Why it matters for agents - Concrete fix - Example (if applicable)
- Quick Wins
- Small, high-impact changes
- Long-Term Improvements
- Architectural or systemic changes
Evaluation Heuristics
1. Clarity & Explicitness
- Are behaviors explicit vs implicit?
- Are types/interfaces well-defined?
- Can intent be inferred locally?
2. Consistency
- Naming conventions
- File/module structure
- Patterns (hooks, services, data access, etc.)
3. Composability
- Are components modular and reusable?
- Are boundaries well-defined?
4. Discoverability
- Can an agent find:
- Entry points? - Core logic? - Data models? - Extension points? - Is there a clear public API surface for modules (index files or documented exports) so agents can consume modules without deep-importing internals?
5. Determinism
- Are side effects controlled and predictable?
- Is behavior testable and reproducible?
6. Testability
- Unit/integration coverage
- Mockability
- Isolation of logic
7. Type Safety / Contracts
- Strong typing or schema validation
- Clear input/output contracts
8. Documentation Quality
- Architecture overview
- Module responsibilities
- Contribution patterns
9. Progressive Disclosure
- Is advanced functionality hidden behind explicit extension points, feature flags, or opt-ins so agents (and humans) can start with a simple surface and progressively explore complexity?
10. Module API Boundaries
- Do modules expose a documented/consistent API surface and avoid consumers importing internal implementation files (deep imports)?
Detection Patterns
Flag when:
- Logic spans multiple unrelated files without clear linkage
- Magic strings / implicit contracts are used
- Dynamic typing obscures structure
- Side effects are hidden (I/O, mutation, globals)
- Functions/classes exceed reasonable complexity
- Inconsistent abstractions exist for similar tasks
- Tests are missing for core logic
- Naming does not reflect intent
Core checks
- Agent metadata file: Detects presence of
AGENTS.md,AGENTS.yaml, orCLAUDE.md. The skill does not require these files, but will flag their absence and recommend creating one as a high-value quick win for onboarding and safe boundaries. - Separation of concerns: Verifies that layers (API/routes, services, data access, UI, infra) are separated and calls out cross-cutting business logic or layer bleed.
- Module API surface / Deep imports: Checks modules expose a clear public API (index files or documented exports) and flags imports that reach into another module's internals (deep imports).
- Progressive disclosure: Checks that advanced or opt-in functionality is hidden behind explicit extension points, feature flags, or well-documented opt-ins rather than exposed at the top level.
Recommendation Patterns
Generate fixes such as:
- Introduce typed interfaces or schemas
- Extract pure functions from side-effect-heavy code
- Standardize patterns (e.g., data access layer, service layer)
- Add index/entry files for discoverability
- Introduce linting/formatting rules
- Add test scaffolding and examples
- Create architecture and extension docs
- Replace implicit behavior with explicit configuration
Output Format (Example)
## Summary
Project is moderately agent-friendly but suffers from implicit behavior and weak structure.
## Key Gaps
- Missing clear service boundaries
- Inconsistent data access patterns
- Lack of type contracts in core flows
## Agent Friction
- Requires cross-file reasoning for simple changes
- Hidden side effects in utility functions
## Recommendations
### 1. Introduce Service Layer (High Impact / Medium Effort)
Problem: Business logic scattered across routes and utils
Fix: Extract into `/services/*` with explicit interfaces
### 2. Add Type Contracts (High Impact / Low Effort)
Problem: Unclear data shapes
Fix: Define shared types or schemas
## Quick Wins
- Add ESLint + Prettier config
- Add README with architecture overview
## Long-Term
- Refactor toward modular domain structureBehavior Guidelines
- Be opinionated but practical
- Prefer concrete fixes over abstract advice
- Optimize for agent comprehension, not just human readability
- Avoid over-engineering recommendations
- Assume the goal is autonomous modification with minimal context