by Haaaiawd
AI-native codebase intelligence skills — generate persistent .nexus-map/ knowledge bases and instantly query file structure, dependency graphs, and change impact. Built for Copilot, Cursor, and any tool-calling LLM. 面向 AI 编程助手的代码库感知技能——生成持久化知识图谱，精准查询文件结构、依赖关系与改动影响半径。
# Add to your Claude Code skills
git clone https://github.com/Haaaiawd/Nexus-skills| Skill | What It Does | When to Use |
|-------|-------------|-------------|
| nexus-mapper | Analyzes the full repository and writes a persistent .nexus-map/ knowledge base for future AI sessions | When starting on an unfamiliar repo, onboarding a team, or preparing for major architectural work |
| nexus-query | Queries file structure, reverse dependencies, change impact radius, and coupling hotspots directly from AST data | During active development — before interface changes, refactoring sprints, or legacy codebase navigation |
Both skills use the same underlying scripts. nexus-query can reuse a .nexus-map/ produced by nexus-mapper, or generate its own ast_nodes.json on demand.
nexus-mapper is a repository-mapping skill for AI agents. It analyzes a local codebase, writes a persistent .nexus-map/ knowledge base, and gives the next session a concrete place to start instead of forcing it to rediscover architecture from scratch.
This is not a generic "summarize the repo" prompt. The skill runs a gated PROBE workflow, challenges its own first-pass assumptions, and only then writes final assets. That design matters: it reduces the usual AI failure mode of turning first impressions into fake certainty.
When the repository contains noisy folders such as third-party static assets, generated trees, or language toolchains, the shared extract_ast.py scanner supports explicit filtering:
--exclude-dirs django_static,.go_root,third_party/assets excludes directory names or repo-relative paths--use-gitignore applies <repo_path>/.gitignore rules and ignores the files and directories declared thereNo comments yet. Be the first to share your thoughts!
--no-gitignore disables only .gitignore rules; built-in noise exclusions and --exclude-dirs still apply.nexus-map/
├── INDEX.md ← Load this first. Full architectural context, under 2000 tokens.
├── arch/
│ ├── systems.md ← Every subsystem: what it owns, exactly where it sits in the repo.
│ ├── dependencies.md ← How components connect. Rendered as a Mermaid dependency graph.
│ └── test_coverage.md ← Static test surface: what is tested, what is not, and where evidence is thin.
├── concepts/
│ ├── concept_model.json ← Machine-readable knowledge graph. Structured for programmatic use.
│ └── domains.md ← The domain language this codebase speaks, in plain terms.
├── hotspots/ ← Present when git metadata is available.
│ └── git_forensics.md ← Files that change constantly, and pairs that always change together.
└── raw/ ← Source data: AST nodes, git statistics, filtered file tree.
INDEX.md is the entry point and routing hub. After reading it, load all five companion files before taking action — they are intentionally kept short (typically under 5000 tokens combined).
nexus-query gives precise, instant answers to structural questions during active development — without reading the entire codebase.
# File skeleton: classes, methods, line numbers, imports
python skills/nexus-query/scripts/query_graph.py ast_nodes.json --file src/core/vision.py
# Reverse dependency: who imports this module?
python skills/nexus-query/scripts/query_graph.py ast_nodes.json --who-imports src.core.vision
# Impact radius: upstream dependencies + downstream dependents
python skills/nexus-query/scripts/query_graph.py ast_nodes.json --impact src/core/vision.py \
--git-stats git_stats.json
# Architectural hub analysis: highest fan-in / fan-out modules
python skills/nexus-query/scripts/query_graph.py ast_nodes.json --hub-analysis
# Per-directory structural summary
python skills/nexus-query/scripts/query_graph.py ast_nodes.json --summary
Zero extra dependencies. Pure Python stdlib. The ast_nodes.json can come from an existing .nexus-map/raw/ or from a fresh extract_ast.py run.
When it matters most:
--who-imports tells you exactly what breaks--impact --git-stats quantifies risk and work scope--file gives you a skeleton map without reading 3000 lines--hub-analysis finds the real coupling hotspots, not just the ones named core/implemented, planned, and inferred. If parsing is partial, it says so.| Requirement | Check |
|-------------|-------|
| Python 3.10+ | python --version |
| Shell execution | Your AI client must support running terminal commands |
A git repository is recommended but not required. Without git history, hotspot analysis is skipped and the rest still runs.
Install script dependencies:
# nexus-mapper
pip install -r skills/nexus-mapper/scripts/requirements.txt
# nexus-query (same dependencies)
pip install -r skills/nexus-query/scripts/requirements.txt
# Full suite
npx skills add haaaiawd/nexus-skills
# Or just the skill you need
npx skills add haaaiawd/nexus-skills/skills/nexus-mapper
npx skills add haaaiawd/nexus-skills/skills/nexus-query
Works with Claude Code, GitHub Copilot, Cursor, Cline, and any client that reads SKILL.md.
Point your AI at a local repository path:
Analyze /Users/me/projects/my-app and generate a knowledge map
The AI runs the protocol and writes .nexus-map/ into the repository root. The next time you work on that codebase, start with:
Read .nexus-map/INDEX.md
For the best long-term behavior, add a short persistent instruction to your host tool's memory file such as AGENTS.md or CLAUDE.md:
.nexus-map/ exists: read INDEX.md to restore context, and follow its routing block for next steps.
.nexus-map/ missing: propose running nexus-mapper before making cross-module or interface changes. If proceeding immediately, run query_graph.py --summary first.
Structural queries: always use query_graph.py to validate dependencies, radius, or boundaries. Never guess from directory names.
Syncing: if a task changes system boundaries, entrypoints, or dependencies, evaluate updating .nexus-map before delivery.
Parses 30+ languages automatically by file extension.
Python · JavaScript · JSX · TypeScript · TSX · Bash · Java · Go · Rust · C++ · C · C# · Kotlin · Ruby · Swift · Scala · PHP · Lua · Elixir · GDScript · Dart · Haskell · Clojure · SQL · Proto · Solidity · Vue · Svelte · R · Perl
Not every listed language has the same depth. Some are full structural parses, some are module-only. The output metadata tells you which is which.
python skills/nexus-mapper/scripts/extract_ast.py <repo_path> \
--add-extension .templ=templ \
--add-query templ struct "(component_declaration name: (identifier) @class.name) @class.def"
nexus-skills/
├── README.md
├── README.zh-CN.md
├── Icon.png
└── skills/
├── nexus-mapper/
│ ├── SKILL.md ← Protocol, guardrails, output schema
│ ├── scripts/
│ │ ├── extract_ast.py ← Multi-language AST extractor
│ │ ├── query_graph.py ← On-demand AST query tool
│ │ ├── git_detective.py ← Git hotspot and coupling analysis
│ │ ├── languages.json ← Language config
│ │ └── requirements.txt
│ └── references/
│ ├── probe-protocol.md ← Full PROBE execution blueprint
│ ├── output-schema.md ← JSON/Markdown schema specs
│ └── language-customization.md ← Extending language support
└── nexus-query/
├── SKILL.md ← Query modes, guardrails, use cases
└── scripts/
├── extract_ast.py
├── query_graph.py
├── git_detective.py
├── languages.json
└── requirements.txt
MIT