gitnexus 1.6.10-rc.22 → 1.6.10-rc.24

package/README.md

@@ -233,7 +233,7 @@ gitnexus analyze --embeddings    # Enable embedding generation (slower, better s
 gitnexus embeddings install      # Fetch the optional local embedding stack on demand (--cuda, --force)
 gitnexus analyze --skills        # Generate repo-specific skill files from detected communities
 gitnexus analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md gitnexus section edits
-gitnexus analyze --skip-skills   # Skip installing .claude/skills/gitnexus/ skill files
+gitnexus analyze --skip-skills   # Skip installing standard .claude/skills/gitnexus-* skill files
 gitnexus analyze --skip-git      # Index folders that are not Git repositories
 gitnexus analyze --workers <n>   # Parse worker pool size (>=1; default: cores-1, capped at 16)
 gitnexus analyze --verbose       # Log skipped files when parsers are unavailable
@@ -328,7 +328,7 @@ GitNexus ships with skill files that teach AI agents how to use the tools effect
 - **Guide** — GitNexus tool/resource/schema reference for the agent
 - **CLI** — Run analyze/status/clean/wiki commands on request
 
-Installed automatically by both `gitnexus analyze` (per-repo) and `gitnexus setup` (global). Run `gitnexus analyze --skills` to additionally generate repo-specific skills for each detected functional area under `.claude/skills/generated/`.
+Installed automatically by both `gitnexus analyze` (per-repo) and `gitnexus setup` (global). Run `gitnexus analyze --skills` to additionally generate each detected functional area as a direct project skill under `.claude/skills/gitnexus-area-<name>/`.
 
 ## Requirements
 

package/dist/cli/ai-context.js

@@ -81,22 +81,22 @@ export function generateGitNexusContent(projectName, stats, opts = {}) {
     const { generatedSkills, groupNames, noStats, skipSkills, runnerPath = '.gitnexus/run.cjs', defaultBranch = 'main', hasPdg = false, } = opts;
     const generatedRows = generatedSkills && generatedSkills.length > 0
         ? generatedSkills
-            .map((s) => `| Work in the ${s.label} area (${s.symbolCount} symbols) | \`.claude/skills/generated/${s.name}/SKILL.md\` |`)
+            .map((s) => `| Work in the ${s.label} area (${s.symbolCount} symbols) | \`.claude/skills/${s.name}/SKILL.md\` |`)
             .join('\n')
         : '';
     // Standard skill rows reference files installed by installSkills(). When
     // --skip-skills suppresses that install, these rows must be omitted — else
     // AGENTS.md/CLAUDE.md would direct agents to read files that don't exist.
-    // Community skills (generatedRows) live in .claude/skills/generated/ and
+    // Community skills (generatedRows) live directly under .claude/skills/ and
     // are independent of --skip-skills, so they remain when present.
     const standardSkillsRows = skipSkills
         ? ''
-        : `| Understand architecture / "How does X work?" | \`.claude/skills/gitnexus/gitnexus-exploring/SKILL.md\` |
-| Blast radius / "What breaks if I change X?" | \`.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md\` |
-| Trace bugs / "Why is X failing?" | \`.claude/skills/gitnexus/gitnexus-debugging/SKILL.md\` |
-| Rename / extract / split / refactor | \`.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md\` |
-| Tools, resources, schema reference | \`.claude/skills/gitnexus/gitnexus-guide/SKILL.md\` |
-| Index, status, clean, wiki CLI commands | \`.claude/skills/gitnexus/gitnexus-cli/SKILL.md\` |`;
+        : `| Understand architecture / "How does X work?" | \`.claude/skills/gitnexus-exploring/SKILL.md\` |
+| Blast radius / "What breaks if I change X?" | \`.claude/skills/gitnexus-impact-analysis/SKILL.md\` |
+| Trace bugs / "Why is X failing?" | \`.claude/skills/gitnexus-debugging/SKILL.md\` |
+| Rename / extract / split / refactor | \`.claude/skills/gitnexus-refactoring/SKILL.md\` |
+| Tools, resources, schema reference | \`.claude/skills/gitnexus-guide/SKILL.md\` |
+| Index, status, clean, wiki CLI commands | \`.claude/skills/gitnexus-cli/SKILL.md\` |`;
     const tableBody = [standardSkillsRows, generatedRows].filter(Boolean).join('\n');
     const skillsTable = tableBody
         ? `| Task | Read this skill file |
@@ -253,11 +253,12 @@ async function upsertGitNexusSection(filePath, content, projectName, stats, noSt
     return 'appended';
 }
 /**
- * Install GitNexus skills to .claude/skills/gitnexus/
+ * Install GitNexus skills as direct children of .claude/skills/
  * Works natively with Claude Code, Cursor, and GitHub Copilot
  */
 async function installSkills(repoPath) {
-    const skillsDir = path.join(repoPath, '.claude', 'skills', 'gitnexus');
+    const skillsDir = path.join(repoPath, '.claude', 'skills');
+    const legacySkillsDir = path.join(skillsDir, 'gitnexus');
     const installedSkills = [];
     // Skill definitions bundled with the package
     const skills = [
@@ -314,6 +315,15 @@ Use GitNexus tools to accomplish this task.
             }
             await fs.writeFile(skillPath, skillContent, 'utf-8');
             installedSkills.push(skill.name);
+            // Previous releases installed these known standard skills one level too
+            // deep. Remove only the child owned by this installer; unknown siblings
+            // under the legacy grouping directory may be user-authored and survive.
+            try {
+                await fs.rm(path.join(legacySkillsDir, skill.name), { recursive: true, force: true });
+            }
+            catch (err) {
+                logger.warn({ err }, `Warning: Could not remove legacy skill ${skill.name}:`);
+            }
         }
         catch (err) {
             // Skip on error, don't fail the whole process
@@ -366,15 +376,15 @@ export async function generateAIContextFiles(repoPath, storagePath, projectName,
         createdFiles.push('AGENTS.md (skipped via --skip-agents-md)');
         createdFiles.push('CLAUDE.md (skipped via --skip-agents-md)');
     }
-    // Install skills to .claude/skills/gitnexus/ (unless --skip-skills)
+    // Install standard skills directly under .claude/skills/ (unless --skip-skills)
     if (!options?.skipSkills) {
         const installedSkills = await installSkills(repoPath);
         if (installedSkills.length > 0) {
-            createdFiles.push(`.claude/skills/gitnexus/ (${installedSkills.length} skills)`);
+            createdFiles.push(`.claude/skills/gitnexus-*/ (${installedSkills.length} skills)`);
         }
     }
     else {
-        createdFiles.push('.claude/skills/gitnexus/ (skipped via --skip-skills)');
+        createdFiles.push('.claude/skills/gitnexus-*/ (skipped via --skip-skills)');
     }
     return { files: createdFiles };
 }

package/dist/cli/analyze.d.ts

@@ -55,7 +55,7 @@ export interface AnalyzeOptions {
      * default-on case.
      */
     stats?: boolean;
-    /** Skip installing standard GitNexus skill files to .claude/skills/gitnexus/. */
+    /** Skip installing standard GitNexus skill files directly under .claude/skills/. */
     skipSkills?: boolean;
     /**
      * Default branch for the generated regression-compare example (#243). From

package/dist/cli/i18n/en.d.ts

@@ -151,7 +151,7 @@ export declare const en: {
     readonly 'help.option.analyze.skills': "Generate repo-specific skill files from detected communities (no-op when --index-only is also set).";
     readonly 'help.option.analyze.skipAgentsMd': "Skip updating the gitnexus section in AGENTS.md and CLAUDE.md";
     readonly 'help.option.analyze.noStats': "Omit volatile file/symbol counts from AGENTS.md and CLAUDE.md";
-    readonly 'help.option.analyze.skipSkills': "Skip installing standard GitNexus skill files under .claude/skills/gitnexus/. Does not suppress community skills from --skills (those use .claude/skills/generated/). Use --index-only to skip all AI-context file injection.";
+    readonly 'help.option.analyze.skipSkills': "Skip installing standard GitNexus skill files directly under .claude/skills/. Does not suppress community skills from --skills (those use .claude/skills/gitnexus-area-*). Use --index-only to skip all AI-context file injection.";
     readonly 'help.option.analyze.indexOnly': "Pure index mode: skip all file injection (AGENTS.md, CLAUDE.md, skills)";
     readonly 'help.option.skipGit': "Treat the provided path/cwd as the index root and skip parent git-root discovery";
     readonly 'help.option.analyze.name': "Register this repo under a custom name in ~/.gitnexus/registry.json (disambiguates repos whose paths share a basename, e.g. two different .../app folders)";

package/dist/cli/i18n/en.js

@@ -151,7 +151,7 @@ export const en = {
     'help.option.analyze.skills': 'Generate repo-specific skill files from detected communities (no-op when --index-only is also set).',
     'help.option.analyze.skipAgentsMd': 'Skip updating the gitnexus section in AGENTS.md and CLAUDE.md',
     'help.option.analyze.noStats': 'Omit volatile file/symbol counts from AGENTS.md and CLAUDE.md',
-    'help.option.analyze.skipSkills': 'Skip installing standard GitNexus skill files under .claude/skills/gitnexus/. Does not suppress community skills from --skills (those use .claude/skills/generated/). Use --index-only to skip all AI-context file injection.',
+    'help.option.analyze.skipSkills': 'Skip installing standard GitNexus skill files directly under .claude/skills/. Does not suppress community skills from --skills (those use .claude/skills/gitnexus-area-*). Use --index-only to skip all AI-context file injection.',
     'help.option.analyze.indexOnly': 'Pure index mode: skip all file injection (AGENTS.md, CLAUDE.md, skills)',
     'help.option.skipGit': 'Treat the provided path/cwd as the index root and skip parent git-root discovery',
     'help.option.analyze.name': 'Register this repo under a custom name in ~/.gitnexus/registry.json (disambiguates repos whose paths share a basename, e.g. two different .../app folders)',

package/dist/cli/i18n/resources.d.ts

@@ -152,7 +152,7 @@ export declare const cliResources: {
         readonly 'help.option.analyze.skills': "Generate repo-specific skill files from detected communities (no-op when --index-only is also set).";
         readonly 'help.option.analyze.skipAgentsMd': "Skip updating the gitnexus section in AGENTS.md and CLAUDE.md";
         readonly 'help.option.analyze.noStats': "Omit volatile file/symbol counts from AGENTS.md and CLAUDE.md";
-        readonly 'help.option.analyze.skipSkills': "Skip installing standard GitNexus skill files under .claude/skills/gitnexus/. Does not suppress community skills from --skills (those use .claude/skills/generated/). Use --index-only to skip all AI-context file injection.";
+        readonly 'help.option.analyze.skipSkills': "Skip installing standard GitNexus skill files directly under .claude/skills/. Does not suppress community skills from --skills (those use .claude/skills/gitnexus-area-*). Use --index-only to skip all AI-context file injection.";
         readonly 'help.option.analyze.indexOnly': "Pure index mode: skip all file injection (AGENTS.md, CLAUDE.md, skills)";
         readonly 'help.option.skipGit': "Treat the provided path/cwd as the index root and skip parent git-root discovery";
         readonly 'help.option.analyze.name': "Register this repo under a custom name in ~/.gitnexus/registry.json (disambiguates repos whose paths share a basename, e.g. two different .../app folders)";

package/dist/cli/i18n/zh-CN.js

@@ -151,7 +151,7 @@ export const zhCN = {
     'help.option.analyze.skills': '根据检测到的社区生成仓库专属 skill 文件（同时设置 --index-only 时无效）。',
     'help.option.analyze.skipAgentsMd': '跳过更新 AGENTS.md 和 CLAUDE.md 中的 gitnexus 区块',
     'help.option.analyze.noStats': '从 AGENTS.md 和 CLAUDE.md 中省略易变的文件/符号计数',
-    'help.option.analyze.skipSkills': '跳过安装 .claude/skills/gitnexus/ 下的标准 GitNexus skill 文件。不抑制 --skills 生成的社区 skill（位于 .claude/skills/generated/）。使用 --index-only 可跳过所有 AI 上下文文件注入。',
+    'help.option.analyze.skipSkills': '跳过直接安装在 .claude/skills/ 下的标准 GitNexus skill 文件。不抑制 --skills 生成的社区 skill（位于 .claude/skills/gitnexus-area-*）。使用 --index-only 可跳过所有 AI 上下文文件注入。',
     'help.option.analyze.indexOnly': '纯索引模式：跳过所有文件注入（AGENTS.md、CLAUDE.md、skills）',
     'help.option.skipGit': '将提供的路径/cwd 视为索引根目录，并跳过向上查找 git 根目录',
     'help.option.analyze.name': '在 ~/.gitnexus/registry.json 中使用自定义名称注册该仓库（用于区分路径 basename 相同的仓库，例如两个不同的 .../app 目录）',

package/dist/cli/index.js

@@ -53,8 +53,8 @@ program
     'Without this flag, analyze always updates the workspace index, which follows the ' +
     'checked-out working tree. Distinct from --default-branch (cosmetic base_ref).')
     .option('--no-stats', 'Omit volatile file/symbol counts from AGENTS.md and CLAUDE.md')
-    .option('--skip-skills', 'Skip installing standard GitNexus skill files under .claude/skills/gitnexus/. ' +
-    'Does not suppress community skills from --skills (those use .claude/skills/generated/). ' +
+    .option('--skip-skills', 'Skip installing standard GitNexus skill files directly under .claude/skills/. ' +
+    'Does not suppress community skills from --skills (those use .claude/skills/gitnexus-area-*). ' +
     'Use --index-only to skip all AI-context file injection.')
     .option('--index-only', 'Pure index mode: skip all file injection (AGENTS.md, CLAUDE.md, skills)')
     .option('--skip-git', 'Treat the provided path/cwd as the index root and skip parent git-root discovery')

package/dist/cli/skill-gen.js

@@ -8,6 +8,9 @@
  */
 import fs from 'fs/promises';
 import path from 'path';
+const GENERATED_SKILL_PREFIX = 'gitnexus-area-';
+const MAX_SKILL_NAME_LENGTH = 64;
+const MAX_COMMUNITY_NAME_LENGTH = MAX_SKILL_NAME_LENGTH - GENERATED_SKILL_PREFIX.length;
 // ============================================================================
 // MAIN EXPORT
 // ============================================================================
@@ -20,7 +23,27 @@ import path from 'path';
  */
 export const generateSkillFiles = async (repoPath, projectName, pipelineResult) => {
     const { communityResult, processResult, graph } = pipelineResult;
-    const outputDir = path.join(repoPath, '.claude', 'skills', 'generated');
+    const outputDir = path.join(repoPath, '.claude', 'skills');
+    const legacyOutputDir = path.join(outputDir, 'generated');
+    // Community skills used to live under an undiscoverable `generated/`
+    // grouping directory. Clear that GitNexus-owned legacy output and
+    // stale direct outputs in the reserved namespace, while preserving every
+    // unrelated project skill under .claude/skills/.
+    try {
+        const entries = await fs.readdir(outputDir, { withFileTypes: true });
+        await Promise.all(entries
+            .filter((entry) => entry.isDirectory() && entry.name.startsWith(GENERATED_SKILL_PREFIX))
+            .map((entry) => fs.rm(path.join(outputDir, entry.name), { recursive: true, force: true })));
+    }
+    catch {
+        /* output root may not exist yet */
+    }
+    try {
+        await fs.rm(legacyOutputDir, { recursive: true, force: true });
+    }
+    catch {
+        /* legacy output may not exist */
+    }
     if (!communityResult || !communityResult.memberships.length) {
         console.log('\n  Skills: no communities detected, skipping skill generation');
         return { skills: [], outputPath: outputDir };
@@ -47,13 +70,8 @@ export const generateSkillFiles = async (repoPath, projectName, pipelineResult)
     // Step 3: Build lookup maps
     const membershipsByComm = buildMembershipMap(communityResult.memberships);
     const nodeIdToCommunityLabel = buildNodeCommunityLabelMap(communityResult.memberships, communities);
-    // Step 4: Clear and recreate output directory
-    try {
-        await fs.rm(outputDir, { recursive: true, force: true });
-    }
-    catch {
-        /* may not exist */
-    }
+    // Step 4: Ensure the shared project-skill root exists. Never clear it: it
+    // also contains user-authored and standard GitNexus skills.
     await fs.mkdir(outputDir, { recursive: true });
     // Step 5: Generate skill files
     const skills = [];
@@ -74,14 +92,15 @@ export const generateSkillFiles = async (repoPath, projectName, pipelineResult)
         // Generate kebab name
         const kebabName = toKebabName(community.label, usedNames);
         usedNames.add(kebabName);
+        const skillName = `${GENERATED_SKILL_PREFIX}${kebabName}`;
         // Generate SKILL.md content
-        const content = renderSkillMarkdown(community, projectName, members, files, entryPoints, flows, connections, kebabName);
+        const content = renderSkillMarkdown(community, projectName, members, files, entryPoints, flows, connections, skillName);
         // Write file
-        const skillDir = path.join(outputDir, kebabName);
+        const skillDir = path.join(outputDir, skillName);
         await fs.mkdir(skillDir, { recursive: true });
         await fs.writeFile(path.join(skillDir, 'SKILL.md'), content, 'utf-8');
         const info = {
-            name: kebabName,
+            name: skillName,
             label: community.label,
             symbolCount: community.symbolCount,
             fileCount: files.length,
@@ -89,7 +108,7 @@ export const generateSkillFiles = async (repoPath, projectName, pipelineResult)
         skills.push(info);
         console.log(`    \u2713 ${community.label} (${community.symbolCount} symbols, ${files.length} files)`);
     }
-    console.log(`\n  ${skills.length} skills generated \u2192 .claude/skills/generated/`);
+    console.log(`\n  ${skills.length} skills generated \u2192 .claude/skills/${GENERATED_SKILL_PREFIX}*/`);
     return { skills, outputPath: outputDir };
 };
 // ============================================================================
@@ -380,10 +399,10 @@ const gatherCrossConnections = (rawIds, ownLabel, membershipsByComm, nodeIdToCom
  * @param {MemberSymbol[]} entryPoints - Exported entry point symbols
  * @param {ProcessNode[]} flows - Execution flows touching this community
  * @param {CrossConnection[]} connections - Cross-community connections
- * @param {string} kebabName - Kebab-case name for the skill
+ * @param {string} skillName - Namespaced kebab-case name for the skill
  * @returns {string} Full SKILL.md content
  */
-const renderSkillMarkdown = (community, projectName, members, files, entryPoints, flows, connections, kebabName) => {
+const renderSkillMarkdown = (community, projectName, members, files, entryPoints, flows, connections, skillName) => {
     const cohesionPct = Math.round(community.cohesion * 100);
     // Dominant directory: most common top-level directory
     const dominantDir = getDominantDirectory(files);
@@ -396,7 +415,7 @@ const renderSkillMarkdown = (community, projectName, members, files, entryPoints
     const lines = [];
     // Frontmatter
     lines.push('---');
-    lines.push(`name: ${kebabName}`);
+    lines.push(`name: ${skillName}`);
     lines.push(`description: "Skill for the ${community.label} area of ${projectName}. ${community.symbolCount} symbols across ${files.length} files."`);
     lines.push('---');
     lines.push('');
@@ -496,20 +515,21 @@ const renderSkillMarkdown = (community, projectName, members, files, entryPoints
  * @brief Convert a community label to a kebab-case directory name
  * @param {string} label - The community label
  * @param {Set<string>} usedNames - Already-used names for collision detection
- * @returns {string} Unique kebab-case name capped at 50 characters
+ * @returns {string} Unique kebab-case name that leaves room for the GitNexus prefix
  */
 const toKebabName = (label, usedNames) => {
     let name = label
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-+|-+$/g, '')
-        .slice(0, 50);
+        .slice(0, MAX_COMMUNITY_NAME_LENGTH);
     if (!name)
         name = 'skill';
     let candidate = name;
     let counter = 2;
     while (usedNames.has(candidate)) {
-        candidate = `${name}-${counter}`;
+        const suffix = `-${counter}`;
+        candidate = `${name.slice(0, MAX_COMMUNITY_NAME_LENGTH - suffix.length)}${suffix}`;
         counter++;
     }
     return candidate;

package/dist/core/run-analyze.d.ts

@@ -47,7 +47,7 @@ export interface AnalyzeOptions {
     skipAgentsMd?: boolean;
     /** Omit volatile symbol/relationship counts from AGENTS.md and CLAUDE.md. */
     noStats?: boolean;
-    /** Skip installing standard GitNexus skill files to .claude/skills/gitnexus/. */
+    /** Skip installing standard GitNexus skill files directly under .claude/skills/. */
     skipSkills?: boolean;
     /**
      * Build the CFG/PDG substrate (#2081 M1). Forwarded to `PipelineOptions.pdg`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.10-rc.22",
+  "version": "1.6.10-rc.24",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",