Nexus-skills
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 编程助手的代码库感知技能——生成持久化知识图谱,精准查询文件结构、依赖关系与改动影响半径。
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/haaaiawd--nexus-skills)HTML
<a href="/listings/haaaiawd--nexus-skills"><img src="/api/listings/haaaiawd--nexus-skills/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
# 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`.
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 214 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <p align="center">
- <img src="Icon.png" alt="nexus-skills" width="96" height="96">
- </p>
- <h1 align="center">nexus-skills</h1>
- <p align="center">
- 为 AI Agent 生成可持续复用的代码仓库知识库,并提供精准的代码结构查询能力。<br>
- Build a persistent knowledge map of any codebase. Query its structure with precision. Every AI session starts smarter.
- </p>
- <p align="center">
- <a href="README.zh-CN.md">中文文档</a>
- </p>
- ---
- ## Two Skills, One Philosophy
- | 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
- 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 there
- - `--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
- nexus-query gives precise, instant answers to structural questions during active development — without reading the entire codebase.
- ```bash
- # 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:**
- - Before any interface change: `--who-imports` tells you exactly what breaks
- - Before a sprint: `--impact --git-stats` quantifies risk and work scope
- - In a legacy codebase: `--file` gives you a skeleton map without reading 3000 lines
- - At architecture review: `--hub-analysis` finds the real coupling hotspots, not just the ones named `core/`
- ---
- ## Why They Are Different
- - **Phase-gated**: nexus-mapper's PROFILE, REASON, OBJECT, BENCHMARK, and EMIT are not optional.
- - **Honest provenance**: Both skills distinguish `implemented`, `planned`, and `inferred`. If parsing is partial, it says so.
- - **Composable**: nexus-query works standalone or on top of a nexus-mapper map.
- - **Optimized for future sessions**: every artifact is designed to be loaded next time, not just this time.
- ---
- ## Prerequisites
- | 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:**
- ```bash
- # nexus-mapper
- pip install -r skills/nexus-mapper/scripts/requirements.txt
- # nexus-query (same dependencies)
- pip install -r skills/nexus-query/scripts/requirements.txt
- ```
- ---
- ## Install
- ```bash
- # 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`.
- ---
- ## How To Use nexus-mapper
- 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`:
- ```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.
- ```
- ---
- ## Language Support
- 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.
- ### Extending language support
- ```bash
- 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"
- ```
- ---
- ## Repository Structure
- ```
- 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
- ```
- ---
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.