holocron/.agents/skills/neuledge-context/SKILL.md

name, description, metadata, allowed-tools

name	description	metadata	allowed-tools
neuledge-context	Use when the user wants to install @neuledge/context, register it as a Claude Code MCP server, manage documentation packages (install, browse, add, remove, list), configure custom registries, or manage auth for private registries. Do NOT use when the user wants to install a different MCP server, wants to query docs from an already-running context server (call `get_docs` directly), or is setting up @neuledge/context for Cursor, VS Code Copilot, or Claude Desktop rather than Claude Code.	category cross-cutting	Bash Read Edit

Required inputs

• Task type — install / register-mcp / package-management / auth / upgrade / uninstall; inferred from user request, ask if ambiguous
• Package name(s) (package management only) — name(s) to install, add, or remove; ask if not stated
• Library list (project MCP scope only) — space-separated lib names for --libs; ask if not stated
• Domain (auth only) — domain to authenticate against; ask if not stated
• Credential reference (auth only) — environment variable or secret manager path holding the token or cookie; never the raw value

Constraints

• Run scripts/setup-neuledge-context.sh <VERSION> for install and upgrade — never run npm install -g @neuledge/context@latest
• Run scripts/secure-context-config.sh immediately after every context auth add — never skip the permissions step
• Check git --version before running context add on a URL or GitHub source; skip the check for local .db file paths
• Never echo, repeat, or log auth token or cookie values — reference the environment variable name only
• Scope all steps to stdio mode; HTTP/Docker mode is documented in references/http-mode.md, not covered here
• State what you are about to do before running setup-neuledge-context.sh — it modifies global npm and Claude Code MCP config

Process

1. Identify task. Infer the task type from the user's request. If the request spans multiple tasks (e.g. install + package install), execute them in the order listed below.

2. Install. (Skip if context --version already returns the target version.)

   • State: "I will run scripts/setup-neuledge-context.sh from the ai-development repo root — this installs @neuledge/context globally at the pinned version."
   • Run: bash scripts/setup-neuledge-context.sh from /root/ai-development/
   • Verify: context --version
   • See references/install-notes.md for prerequisites and native SQLite build tool requirements.

3. Register global MCP server. (One-time per machine. Skip if already registered at user scope.)

   • Check: claude mcp list | grep '^context ' — if output is non-empty, skip.
   • Run: claude mcp add -s user context -- context serve
   • Confirm: claude mcp list
   • Note: the default scope for claude mcp add is local (machine-specific, not shared). Always pass -s user for global availability across all projects.
   • Note: MCP tools (search_packages, get_docs, download_package) only appear in the active session after /reload-plugins or starting a new session — they are not immediately available mid-session after registration.

4. Scope MCP to specific libraries (optional, per-project). (When user wants to restrict the MCP session to pre-approved libraries for a project.)

   • Collect the library list from the user if not stated.
   • Verify each identifier: run context list — copy the identifier exactly as shown, including any version suffix (e.g., claude-code-docs@latest, not claude-code-docs). The --libs filter does an exact string match; a bare name without the suffix will silently exclude the package and get_docs will return "Package not found". For registry packages not yet installed, use context browse <name> to find the name, then install and re-run context list.
   • Run: claude mcp add -s project context -- context serve --libs <verified-id1> <verified-id2> ...
   • This writes to .mcp.json in the project root — commit this file to share the scope with the team.
   • .mcp.json can also be edited directly if the identifier list needs updating. Changes take effect only in a new Claude Code session — /reload-plugins reloads skill manifests but does not restart stdio MCP server processes.
   • If both user and project scopes exist for the same server name, Claude Code will warn about dual registration — this is expected. Project scope overrides user scope within the project directory.
   • Note: with --libs, the search_packages and download_package MCP tools are hidden; only get_docs is available for the listed libraries.

5. Manage packages.

   • Browse registry: context browse <name> — shows available versions. The public registry is JS/frontend-focused; key AI/agent packages (Anthropic SDK, Claude Code, MCP SDK) are absent — use context add for those.
   • Install from registry: context install <registry/name> [version] — e.g. context install npm/react.
   • Add from source (for registry gaps): Many docs sites publish llms.txt; prefer that over cloning. Check <url>/llms.txt or <url>/llms-full.txt before falling back to GitHub. Check git --version first if source is a GitHub repo URL.

     context add https://docs.anthropic.com --name claude-docs          # llms.txt site
     context add https://modelcontextprotocol.io --name mcp-docs        # llms.txt site
     context add https://github.com/org/repo --path docs --name mylib   # GitHub repo
     

     See references/context-cli-reference.md for all flags.
   • List installed: context list — shows name, version, size, and section count. Section count is a health signal: a package with 0 or very few sections relative to its KB size was probably not indexed correctly.
   • Remove: context remove <name>@<version> to target a specific version; context remove <name> removes all versions — confirm with the user before removing all.
   • Rebuild (when a package returns no query results): A package can install successfully but produce no FTS5 search results if the source URL returned sparse content (e.g., a redirect page instead of the actual docs). Diagnose by checking section count in context list — a large KB size with few sections is a sign of a bad crawl. Fix: context remove <name> (confirm first), then re-add from a better source. Try <url>/llms-full.txt before <url>/llms.txt before the GitHub repo — llms-full.txt produces the most sections. After rebuild, verify with context list that section count has increased and spot-check with context query <name> <topic>.

6. Configure auth. (Private registries or subscriber-only content.)

   • Run: context auth add <domain> --header "Authorization: Bearer $TOKEN" — use the environment variable name, not the value.
   • Immediately run: bash scripts/secure-context-config.sh from /root/ai-development/

7. Configure custom registry. (Self-hosted registry server.)

   • Read ~/.context/config.json. Add a server entry following the schema in references/context-cli-reference.md.
   • Test: context browse <package> --server <name>

8. Upgrade. Run bash scripts/setup-neuledge-context.sh <TARGET_VERSION> from /root/ai-development/. The script checks the current version and skips if already at target.

9. Uninstall.

   • Run: npm uninstall -g @neuledge/context
   • Ask the user before removing downloaded packages: rm -rf ~/.context deletes all installed documentation and config — confirm before running.

Output format

No structured output file. The skill produces terminal confirmation of each completed step. Artifacts:

• @neuledge/context installed globally at pinned version
• MCP server entry in user config (global, -s user) or .mcp.json in project root (project-scoped, -s project, committed to repo)
• Downloaded .db packages in ~/.context/packages/
• Modified ~/.context/config.json (auth entries, registry config)

Failure handling

• scripts/setup-neuledge-context.sh not found — stop; instruct user to run from /root/ai-development/
• context binary not found after install — report npm error; check node --version is ≥18
• MCP registration fails — run claude mcp list to check for name conflicts; if context is registered with different args or at the wrong scope, remove with claude mcp remove context -s <scope> and re-add at the correct scope
• MCP tools not visible after registration — claude mcp add mid-session does not immediately expose tools; run /reload-plugins or start a new session
• Dual-scope warning after adding project scope — expected when user and project scopes both define context; project takes precedence in the project directory. Remove the unwanted scope with claude mcp remove context -s <scope>
• context add fails with "git not found" — advise apt-get install git (Debian/Ubuntu) or equivalent; re-run after install
• Native SQLite build failure — Context falls back to WASM automatically; advise installing build tools for better performance: apt-get install -y python3 make g++ on Debian/Ubuntu. See references/install-notes.md for known gotchas.
• get_docs returns "Package not found" for a package that appears in context list — two causes: (1) --libs identifier mismatch: the identifier in .mcp.json must exactly match context list output including version suffix; edit .mcp.json and start a new session to apply; (2) bad crawl: the package indexed 0 or very few sections — rebuild per the Rebuild workflow in step 5.
• get_docs returns results via CLI (context query) but not via MCP — the MCP server process is using the old --libs config from when the session started; changes to .mcp.json require a new session, /reload-plugins is not sufficient.

Self-check

• Task type identified before any commands run
• setup-neuledge-context.sh announced before execution
• claude mcp list checked before claude mcp add — skipped if already registered at correct scope
• -s user used for global registration; -s project used for --libs project scope — never relied on default (local) scope
• context list used to get authoritative identifiers before composing --libs — identifiers copied verbatim including version suffix (e.g., name@latest)
• .mcp.json noted for commit when project scope is added
• git --version checked before context add on a URL or GitHub source
• Auth step: secure-context-config.sh run immediately after every context auth add
• No credential values echoed or logged — environment variable references only
• context remove <name>@<version> used (not bare name) when targeting a specific version
• rm -rf ~/.context confirmed with user before running