Nexus-skills

Two Skills, One Philosophy

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.

# 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

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

Install

# 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:

.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

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