Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/haaaiawd--nexus-skills/badge.svg)](/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

i

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)

  1. <p align="center">
  2. <img src="Icon.png" alt="nexus-skills" width="96" height="96">
  3. </p>
  4. <h1 align="center">nexus-skills</h1>
  5. <p align="center">
  6. 为 AI Agent 生成可持续复用的代码仓库知识库,并提供精准的代码结构查询能力。<br>
  7. Build a persistent knowledge map of any codebase. Query its structure with precision. Every AI session starts smarter.
  8. </p>
  9. <p align="center">
  10. <a href="README.zh-CN.md">中文文档</a>
  11. </p>
  12. ---
  13. ## Two Skills, One Philosophy
  14. | Skill | What It Does | When to Use |
  15. |-------|-------------|-------------|
  16. | **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 |
  17. | **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 |
  18. 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.
  19. ---
  20. ## nexus-mapper
  21. 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.
  22. 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.
  23. 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:
  24. - `--exclude-dirs django_static,.go_root,third_party/assets` excludes directory names or repo-relative paths
  25. - `--use-gitignore` applies `<repo_path>/.gitignore` rules and ignores the files and directories declared there
  26. - `--no-gitignore` disables only `.gitignore` rules; built-in noise exclusions and `--exclude-dirs` still apply
  27. ```
  28. .nexus-map/
  29. ├── INDEX.md ← Load this first. Full architectural context, under 2000 tokens.
  30. ├── arch/
  31. │ ├── systems.md ← Every subsystem: what it owns, exactly where it sits in the repo.
  32. │ ├── dependencies.md ← How components connect. Rendered as a Mermaid dependency graph.
  33. │ └── test_coverage.md ← Static test surface: what is tested, what is not, and where evidence is thin.
  34. ├── concepts/
  35. │ ├── concept_model.json ← Machine-readable knowledge graph. Structured for programmatic use.
  36. │ └── domains.md ← The domain language this codebase speaks, in plain terms.
  37. ├── hotspots/ ← Present when git metadata is available.
  38. │ └── git_forensics.md ← Files that change constantly, and pairs that always change together.
  39. └── raw/ ← Source data: AST nodes, git statistics, filtered file tree.
  40. ```
  41. `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).
  42. ---
  43. ## nexus-query
  44. nexus-query gives precise, instant answers to structural questions during active development — without reading the entire codebase.
  45. ```bash
  46. # File skeleton: classes, methods, line numbers, imports
  47. python skills/nexus-query/scripts/query_graph.py ast_nodes.json --file src/core/vision.py
  48. # Reverse dependency: who imports this module?
  49. python skills/nexus-query/scripts/query_graph.py ast_nodes.json --who-imports src.core.vision
  50. # Impact radius: upstream dependencies + downstream dependents
  51. python skills/nexus-query/scripts/query_graph.py ast_nodes.json --impact src/core/vision.py \
  52. --git-stats git_stats.json
  53. # Architectural hub analysis: highest fan-in / fan-out modules
  54. python skills/nexus-query/scripts/query_graph.py ast_nodes.json --hub-analysis
  55. # Per-directory structural summary
  56. python skills/nexus-query/scripts/query_graph.py ast_nodes.json --summary
  57. ```
  58. 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.
  59. **When it matters most:**
  60. - Before any interface change: `--who-imports` tells you exactly what breaks
  61. - Before a sprint: `--impact --git-stats` quantifies risk and work scope
  62. - In a legacy codebase: `--file` gives you a skeleton map without reading 3000 lines
  63. - At architecture review: `--hub-analysis` finds the real coupling hotspots, not just the ones named `core/`
  64. ---
  65. ## Why They Are Different
  66. - **Phase-gated**: nexus-mapper's PROFILE, REASON, OBJECT, BENCHMARK, and EMIT are not optional.
  67. - **Honest provenance**: Both skills distinguish `implemented`, `planned`, and `inferred`. If parsing is partial, it says so.
  68. - **Composable**: nexus-query works standalone or on top of a nexus-mapper map.
  69. - **Optimized for future sessions**: every artifact is designed to be loaded next time, not just this time.
  70. ---
  71. ## Prerequisites
  72. | Requirement | Check |
  73. |-------------|-------|
  74. | Python 3.10+ | `python --version` |
  75. | Shell execution | Your AI client must support running terminal commands |
  76. A git repository is recommended but not required. Without git history, hotspot analysis is skipped and the rest still runs.
  77. **Install script dependencies:**
  78. ```bash
  79. # nexus-mapper
  80. pip install -r skills/nexus-mapper/scripts/requirements.txt
  81. # nexus-query (same dependencies)
  82. pip install -r skills/nexus-query/scripts/requirements.txt
  83. ```
  84. ---
  85. ## Install
  86. ```bash
  87. # Full suite
  88. npx skills add haaaiawd/nexus-skills
  89. # Or just the skill you need
  90. npx skills add haaaiawd/nexus-skills/skills/nexus-mapper
  91. npx skills add haaaiawd/nexus-skills/skills/nexus-query
  92. ```
  93. Works with Claude Code, GitHub Copilot, Cursor, Cline, and any client that reads `SKILL.md`.
  94. ---
  95. ## How To Use nexus-mapper
  96. Point your AI at a local repository path:
  97. ```
  98. Analyze /Users/me/projects/my-app and generate a knowledge map
  99. ```
  100. The AI runs the protocol and writes `.nexus-map/` into the repository root. The next time you work on that codebase, start with:
  101. ```
  102. Read .nexus-map/INDEX.md
  103. ```
  104. 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`:
  105. ```md
  106. .nexus-map/ exists: read INDEX.md to restore context, and follow its routing block for next steps.
  107. .nexus-map/ missing: propose running nexus-mapper before making cross-module or interface changes. If proceeding immediately, run query_graph.py --summary first.
  108. Structural queries: always use query_graph.py to validate dependencies, radius, or boundaries. Never guess from directory names.
  109. Syncing: if a task changes system boundaries, entrypoints, or dependencies, evaluate updating .nexus-map before delivery.
  110. ```
  111. ---
  112. ## Language Support
  113. Parses 30+ languages automatically by file extension.
  114. 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
  115. 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.
  116. ### Extending language support
  117. ```bash
  118. python skills/nexus-mapper/scripts/extract_ast.py <repo_path> \
  119. --add-extension .templ=templ \
  120. --add-query templ struct "(component_declaration name: (identifier) @class.name) @class.def"
  121. ```
  122. ---
  123. ## Repository Structure
  124. ```
  125. nexus-skills/
  126. ├── README.md
  127. ├── README.zh-CN.md
  128. ├── Icon.png
  129. └── skills/
  130. ├── nexus-mapper/
  131. │ ├── SKILL.md ← Protocol, guardrails, output schema
  132. │ ├── scripts/
  133. │ │ ├── extract_ast.py ← Multi-language AST extractor
  134. │ │ ├── query_graph.py ← On-demand AST query tool
  135. │ │ ├── git_detective.py ← Git hotspot and coupling analysis
  136. │ │ ├── languages.json ← Language config
  137. │ │ └── requirements.txt
  138. │ └── references/
  139. │ ├── probe-protocol.md ← Full PROBE execution blueprint
  140. │ ├── output-schema.md ← JSON/Markdown schema specs
  141. │ └── language-customization.md ← Extending language support
  142. └── nexus-query/
  143. ├── SKILL.md ← Query modes, guardrails, use cases
  144. └── scripts/
  145. ├── extract_ast.py
  146. ├── query_graph.py
  147. ├── git_detective.py
  148. ├── languages.json
  149. └── requirements.txt
  150. ```
  151. ---
  152. ## License
  153. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.