AI Maturity ScannerLocal CLI for AI coding maturity
中文EN

Docs

Install, run, and export reports.

AI Maturity Scanner is a standalone Node.js CLI. It requires Node 22+ and git on PATH.

Common workflows

Choose the command by report destination: image for sharing, Markdown for docs and PRs, JSON for automation.

Generate the default image report

# Scan the current directory and write ./ai-maturity-report.png
ai-maturity-scanner

Scan a target repository

# Scan ./my-repo and write the default PNG image report
ai-maturity-scanner ./my-repo

Export a Markdown report

# Useful for docs, issues, or PR comments
ai-maturity-scanner ./my-repo --format md --out report.md

Export JSON for automation

# Useful for CI, dashboards, or threshold checks
ai-maturity-scanner ./my-repo --format json --out report.json

Generate an English report

# Render report text in English
ai-maturity-scanner ./my-repo --lang en

Spec file configuration

By default the scanner treats Markdown files under the repo's specs/ directory as spec documents. If your specs live elsewhere (e.g. docs/specs/, design/), customize the match with a config file at the repo root or the --spec-glob flag. Precedence: --spec-glob flag > config file > default.

Place .ai-maturity-scanner.json at the repository root with a specGlobs array:

{
  "specGlobs": [
    "docs/specs/**/*.md",
    "design/**/*.md"
  ]
}

Or pass --spec-glob on the command line (repeatable; overrides the config file):

# Treat only Markdown under docs/specs as specs
ai-maturity-scanner ./my-repo --spec-glob 'docs/specs/**/*.md'

With no configuration the default glob **/specs/**/*.md is used (specs/ at any depth, Markdown only: .md/.mdx/.mdc).

  • Globs use forward slashes as path separators (same as .gitignore, tsconfig, etc.) — use / on Windows too.
  • If the config file is malformed or has the wrong shape, the scanner logs a warning and falls back to the default; it never aborts the scan.
  • Spec configuration only affects file grouping in the report; it does not change the AMI score or level.

MCP support boundary

MCP configuration does not have one repository-level format across coding assistants, so current detection is intentionally incomplete. For now, only Claude Code project .mcp.json / mcp.json files and Codex project .codex/config.toml are treated as explicitly supported MCP configuration sources.

  • Claude Code: .mcp.json / mcp.json
  • Codex: .codex/config.toml

Other tools may also support MCP, but their paths, fields, precedence rules, and public documentation vary. To avoid false positives, the scanner does not treat those formats as stable supported inputs.

Scoring reference

This section keeps the algorithm details available for implementation and threshold checks. For report interpretation, start with the Metrics page.

Normalization

Each raw metric is mapped to a 0–100 score by linear saturation: it grows proportionally until the cap, then stays at 100.

score = min(raw, cap) / cap × 100

Saturation caps

MetricCap
skill_count30
skill_line_count15000
advanced_skill_count10
skill_resource_count30
agent_count10
agent_line_count2000
command_count10
command_line_count2000
mcp_count3
ai_instruction_files1
specs_file_count50
specs_line_count5000
subproject_coverage5

Special normalization

instruction_max_line_count

Scored piecewise (non-linear): 0 lines→10, 0–20→10–30, 20–50→30–100, 50–400→100 (sweet spot), 400–1000→100–30, above 1000→10.

skill_engineering_rate

rate = advanced_skill_count / skill_count (0 when skill_count is 0); the rate reaches 100 at 0.50.

AMI weighting

Normalized metrics roll up into three dimensions, which are then weighted into the 0–100 AMI score (rounded to two decimals).

Dimension rollup

configuration_depth60%

Mean of the skill, agent, command, and mcp subscores.

context_richness30%

Mean of ai_instruction_files, instruction_max_line_count, specs_file_count, and specs_line_count.

integration_breadth10%

Normalized subproject_coverage.

configuration_depth subscore groups

  • skill subscore = Mean of skill_count, skill_line_count, advanced_skill_count, skill_engineering_rate, and skill_resource_count
  • agent subscore = Mean of agent_count and agent_line_count
  • command subscore = Mean of command_count and command_line_count
  • mcp subscore = mcp_count

AMI formula

AMI = configuration_depth × 0.6 + context_richness × 0.3 + integration_breadth × 0.1
L0–L4 level algorithm

These five metrics feed the L0–L4 cascade. ability_applied and skill_engineering_rate are derived from other raw metrics and computed separately; the remaining three are raw counts gathered directly during the scan.

Derived metrics

ability_applied= skill + skill_resource + agent + command + mcp

Total applied capability assets; config and hook files are excluded.

Example: skill=3, skill_resource=2, agent=1, command=1, mcp=0 → ability_applied = 3+2+1+1+0 = 7

skill_engineering_rate= advanced_skill_count / skill_count

Share of advanced skills among all skills; 0 when skill_count is 0.

Example: advanced_skill=3, skill=10 → skill_engineering_rate = 3/10 = 0.30

Raw counts

advanced_skill

Number of skills whose directory contains scripts.

specs_files

Number of Markdown files recognized as specs.

ai_instruction_files

Number of AI instruction files in the repository.

The maturity level is a threshold cascade: an L0 gate is checked first, then conditions are evaluated top-down from L4; the first level whose conditions are all met is returned, defaulting to L1. See Threshold metrics above for what each metric means.

LevelConditions (evaluated top-down, first match wins)
L0
ai_instruction_files<1
L4
ability_applied≥25andskill_engineering_rate≥0.40andspecs_files≥20
L3
ability_applied≥15andadvanced_skill≥2andskill_engineering_rate≥0.15andspecs_files≥10
L2
ability_applied≥8andadvanced_skill≥1
L1
Default: returned when none of the above conditions are met.

Repository profile

Repository profile guide

A repository profile describes the most visible shape of AI collaboration assets. It is not another maturity grade and makes no claim about developer proficiency, actual adoption, or code quality.

Primary profile

Every report has exactly one primary profile: the strongest collaboration pattern visible in the repository.

Awaiting Start

unstarted

A neutral state: no AI instruction file was found.

ai_instruction_files = 0

Collaboration Seedling

early-collaboration

Basic collaboration signals exist, without a more distinctive asset pattern yet.

An AI instruction file exists, but no specialized primary is eligible

AI Collaboration Hub

ai-operating-system

A broad and balanced collaboration system.

configuration_depth, context_richness, and integration_breadth are each ≥ 60, with at least three non-zero capability classes

Skill Workshop

skill-workshop

Reusable, engineered skills are the dominant visible asset.

skill_score ≥ 50 and skill_engineering_rate ≥ 0.15

Agent Troupe

agent-troupe

Distinct agent roles form a defining collaboration pattern.

agent_count ≥ 3 and agent_type_distinct ≥ 3

Command Center

command-center

Reusable commands are the defining interaction surface.

command_score ≥ 40 and command_count ≥ 3

Knowledge Library

knowledge-library

Specifications and substantive written AI context are the dominant visible asset.

specs_file_count ≥ 20, context_richness ≥ 65, instruction_max_line_count ≥ 50, and spec_library_score ≥ 50

Traits

Each trait gets a 0–100 degree from existing normalized metrics, bucketed into high, medium, or low by uniform 40/70 bars; the report shows the three highest-degree traits, suppressing any trait already expressed by the primary. A trait with no relevant assets is rated low.

Engineered Skills

engineered-skills

Suppressed when skill-workshop is already the primary.

degree = mean(advanced_skill_count, skill_engineering_rate)

Multi-Agent Collaboration

multi-agent

Suppressed when agent-troupe is already the primary.

degree = mean(agent_count, agent_role_score)

Deep Tool Connectivity

tool-connected

MCP remains a trait and never becomes a primary.

degree = mcp_count

Structured Context

structured-context

Suppressed when knowledge-library is already the primary.

degree = mean(instruction_max_line_count, specs_file_count)

Cross-Project Coverage

cross-project

Cross-project coverage remains a trait and never becomes a primary.

degree = subproject_coverage

How profiles are selected and explained

  1. The evaluator reuses only the report's existing raw metrics, normalized metrics, and three dimensions; it collects or infers no new behavioral data.
  2. With no AI instruction file, the primary is unstarted. Otherwise, each specialized primary is checked for eligibility.
  3. Eligible primary candidates are compared by strength beyond their eligibility floors, rounded to two decimals, with a fixed order breaking only equal rounded strengths; each trait's degree ranks the top three, bucketed into high, medium, or low by the uniform 40/70 bars.
  4. The report retains the matched rule ID and metric facts, each candidate's headroom components and rounded strength, and its selected status so the winner can be compared with alternatives.

Relationship to AMI and L0–L4

AMI and L0–L4 continue to answer how much AI collaboration infrastructure is present and which maturity threshold it reaches. The profile answers which collaboration shape is most visible. It is additive: it does not change raw metrics, normalized metrics, dimensions, the AMI score, or the L0–L4 result.

CLI reference

Formats, output paths, language, privacy mode, and spec matching are covered here in one place.

FlagValuesDefaultDescription
[path]repository path.Git repository path to scan; omitted path means the current directory.
-f, --format <format>png | terminal | md | jsonpngSelect the report format: image, terminal text, Markdown, or JSON.
-o, --out <file>file pathai-maturity-report.png for PNG; stdout for textWrite the report to a file. Text formats write to stdout when --out is omitted.
-l, --lang <lang>zh | enzhSelect report language.
-V, --versionbooleanfalsePrint the current package version and exit without scanning.
--redactedbooleanfalsePrivacy mode: hide the repository address display field in PNG output.
--verbosebooleanfalseWhen primary output is written to a file, also print a terminal report to stdout.
-g, --spec-glob <glob>glob (repeatable)**/specs/**/*.mdCustomize spec file matching; repeatable and higher priority than the config file.

Subcommands

verify-image <file>

Verify hidden fingerprint metadata in a generated PNG report.