feat(cli): add --skip-skills and --index-only flags to analyze (resubmit of #742) (#1485)

* feat(cli): add --skip-skills and --index-only flags to analyze command

The `installSkills()` call in `generateAIContextFiles()` runs
unconditionally, injecting 6 skill files into `.claude/skills/gitnexus/`
even when `--skip-agents-md` is passed. This is problematic for bulk
indexing operations on read-only mirrors or third-party repos.

Add two new flags:
- `--skip-skills`: suppress standard GitNexus skill file injection
- `--index-only`: pure index mode that suppresses all file injection
  (AGENTS.md, CLAUDE.md, and skills), writing only to `.gitnexus/`

This gives users three levels of control:
- `--skip-agents-md` — suppress only root context files
- `--skip-skills` — suppress only skill injection
- `--index-only` — suppress everything (pure indexing)

Discovery context: while bulk-indexing 176 repos with
`--skip-agents-md`, all 144 indexed repos were contaminated with
`.claude/skills/gitnexus/` files requiring manual cleanup.

* fix(cli): address PR #742 review — gate community skills, drop dangling refs, add tests

Bot review (#742) flagged three issues with the original commit:

1. `--index-only --skills` still wrote community-derived skill files
   to `.claude/skills/generated/`. The `--skills` branch in analyze.ts
   was not gated by `skipAll`, so the "skip all file injection" contract
   was violated. Gate `generateSkillFiles()` with `!skipAll` so
   `--index-only` truly wins over `--skills`.

2. `--skip-skills` without `--skip-agents-md` produced AGENTS.md /
   CLAUDE.md that still referenced `.claude/skills/gitnexus/*/SKILL.md`
   files that were never installed — every agent load incurred 6
   failed reads. Pass `skipSkills` through to `generateGitNexusContent()`
   and omit the standard-skill rows (and the entire `## CLI` heading
   when the table is empty). Community skills, when present via
   `--skills`, are unaffected.

3. No filesystem tests for `skipSkills` / `indexOnly`. Add three
   regression guards to `test/unit/ai-context.test.ts`:
   - `.claude/skills/gitnexus/` is NOT created when skipSkills=true
   - Nothing is written when both skipAgentsMd and skipSkills are true
     (the resolved-flag state from --index-only)
   - AGENTS.md/CLAUDE.md routing table omits standard skill references
     when skipSkills=true, but preserves the load-bearing imperative
     sections (Always Do / Never Do / Resources)

* test(cli): PR 1485 review follow-ups (help text, gate test, --skip-skills docs)

- Assert --skip-skills and --index-only in analyze --help (skip-git-cli.test.ts).

- Export shouldGenerateCommunitySkillFiles; unit-test index-only+skills gate.

- Clarify --skip-skills does not suppress --skills community files; --index-only for full skip.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(cli): warn when --index-only silently overrides --skills

Address review findings on PR 1485 follow-ups:
- analyze.ts emits a one-line note when both --index-only and --skills
  are set, so users see why a pipeline re-index ran with no skill files
  written.
- index.ts --skills help text now flags the --index-only override.
- shouldGenerateCommunitySkillFiles JSDoc documents the dual role of
  the gate (community skills + AGENTS.md/CLAUDE.md re-generation).
- skip-git-cli.test.ts pins the override-warning surface end-to-end.

---------

Co-authored-by: Gergő Magyar <gergomagyar@icloud.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
achianuri 2026-05-11 07:00:58 -07:00 committed by GitHub
parent 622f98ade5
commit fdf1effb2a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
7 changed files with 250 additions and 16 deletions

View file

@ -28,6 +28,7 @@ interface RepoStats {
export interface AIContextOptions {
skipAgentsMd?: boolean;
noStats?: boolean;
skipSkills?: boolean;
}
const GITNEXUS_START_MARKER = '<!-- gitnexus:start -->';
@ -94,6 +95,7 @@ function generateGitNexusContent(
generatedSkills?: GeneratedSkillInfo[],
groupNames?: string[],
noStats?: boolean,
skipSkills?: boolean,
): string {
const generatedRows =
generatedSkills && generatedSkills.length > 0
@ -105,14 +107,26 @@ function generateGitNexusContent(
.join('\n')
: '';
const skillsTable = `| Task | Read this skill file |
|------|---------------------|
| Understand architecture / "How does X work?" | \`.claude/skills/gitnexus/gitnexus-exploring/SKILL.md\` |
// 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
// 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\` |${generatedRows ? '\n' + generatedRows : ''}`;
| Index, status, clean, wiki CLI commands | \`.claude/skills/gitnexus/gitnexus-cli/SKILL.md\` |`;
const tableBody = [standardSkillsRows, generatedRows].filter(Boolean).join('\n');
const skillsTable = tableBody
? `| Task | Read this skill file |
|------|---------------------|
${tableBody}`
: '';
return `${GITNEXUS_START_MARKER}
# GitNexus Code Intelligence
@ -153,11 +167,15 @@ This repository is listed under GitNexus **group(s): ${groupNames.join(', ')}**
`
: ''
}## CLI
}${
skillsTable
? `## CLI
${skillsTable}
${GITNEXUS_END_MARKER}`;
`
: ''
}${GITNEXUS_END_MARKER}`;
}
/**
@ -319,6 +337,7 @@ export async function generateAIContextFiles(
generatedSkills,
groupNames,
options?.noStats,
options?.skipSkills,
);
const createdFiles: string[] = [];
@ -337,10 +356,14 @@ export async function generateAIContextFiles(
createdFiles.push('CLAUDE.md (skipped via --skip-agents-md)');
}
// Install skills to .claude/skills/gitnexus/
const installedSkills = await installSkills(repoPath);
if (installedSkills.length > 0) {
createdFiles.push(`.claude/skills/gitnexus/ (${installedSkills.length} skills)`);
// Install skills to .claude/skills/gitnexus/ (unless --skip-skills)
if (!options?.skipSkills) {
const installedSkills = await installSkills(repoPath);
if (installedSkills.length > 0) {
createdFiles.push(`.claude/skills/gitnexus/ (${installedSkills.length} skills)`);
}
} else {
createdFiles.push('.claude/skills/gitnexus/ (skipped via --skip-skills)');
}
return { files: createdFiles };

View file

@ -119,6 +119,10 @@ 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/. */
skipSkills?: boolean;
/** Pure index mode: skip all file injection (AGENTS.md, CLAUDE.md, skills). */
indexOnly?: boolean;
/** Index the folder even when no .git directory is present. */
skipGit?: boolean;
/**
@ -150,6 +154,24 @@ export interface AnalyzeOptions {
embeddingDevice?: string;
}
/**
* Whether the post-index skill step should run.
*
* The gated block does two things in sequence: (1) generates the community
* skill files from `--skills`, and (2) re-runs `generateAIContextFiles` so
* AGENTS.md/CLAUDE.md can reference the freshly written skills. Both are
* suppressed together `--index-only` drops the entire step, not just the
* community-skill write. Name retained for the test contract; see call site
* in `analyzeCommand` for the AGENTS.md/CLAUDE.md re-generation it also gates.
*
* Kept as a pure helper so the `--index-only --skills` contract is unit-tested
* without booting the full analyze pipeline (#742 review).
*/
export const shouldGenerateCommunitySkillFiles = (
options: Pick<AnalyzeOptions, 'skills' | 'indexOnly'> | undefined,
pipelineResult: unknown,
): boolean => Boolean(options?.skills && pipelineResult && !options?.indexOnly);
export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOptions) => {
if (ensureHeap()) return;
@ -245,6 +267,18 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
console.log('\n GitNexus Analyzer\n');
// `--index-only` is the stronger contract — it suppresses every form of file
// injection, including community skill writes that `--skills` would normally
// produce. Surface the override explicitly so users don't wonder why a
// pipeline re-index ran but no skill files appeared. The pipeline still
// re-runs (see `force: options?.force || options?.skills` below); the warning
// is purely about the dropped post-index write step.
if (options?.indexOnly && options?.skills) {
console.log(
' Note: --index-only overrides --skills; community skill files will not be written.\n',
);
}
let repoPath: string;
if (inputPath) {
repoPath = path.resolve(inputPath);
@ -399,6 +433,9 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
// ── Run shared analysis orchestrator ───────────────────────────────
try {
const skipAll = options?.indexOnly;
const skipAgentsMd = skipAll || options?.skipAgentsMd;
const skipSkills = skipAll || options?.skipSkills;
const result = await runFullAnalysis(
repoPath,
{
@ -410,7 +447,8 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
embeddingsNodeLimit,
dropEmbeddings: options?.dropEmbeddings,
skipGit: options?.skipGit,
skipAgentsMd: options?.skipAgentsMd,
skipAgentsMd,
skipSkills,
noStats: options?.noStats,
registryName: options?.name,
// Registry-collision bypass — its own CLI flag, intentionally NOT
@ -456,8 +494,10 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
// a healthy index.
await assertAnalysisFinalized(repoPath);
// Skill generation (CLI-only, uses pipeline result from analysis)
if (options?.skills && result.pipelineResult) {
// Skill generation (CLI-only, uses pipeline result from analysis).
// Gated so `--index-only --skills` skips community skill writes too
// (`shouldGenerateCommunitySkillFiles` — see unit test).
if (shouldGenerateCommunitySkillFiles(options, result.pipelineResult)) {
updateBar(99, 'Generating skill files...');
try {
const { generateSkillFiles } = await import('./skill-gen.js');
@ -497,7 +537,7 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
processes: s.processes,
},
skillResult.skills,
{ skipAgentsMd: options?.skipAgentsMd, noStats: options?.noStats },
{ skipAgentsMd, skipSkills, noStats: options?.noStats },
);
}
} catch {

View file

@ -33,9 +33,20 @@ program
'Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` ' +
'preserves any embeddings already present in the index.',
)
.option('--skills', 'Generate repo-specific skill files from detected communities')
.option(
'--skills',
'Generate repo-specific skill files from detected communities ' +
'(no-op when --index-only is also set).',
)
.option('--skip-agents-md', 'Skip updating the gitnexus section in AGENTS.md and CLAUDE.md')
.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/). ' +
'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',

View file

@ -81,6 +81,8 @@ 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/. */
skipSkills?: boolean;
/**
* User-provided alias for the registry `name` (#829). When set,
* forwarded to `registerRepo` so the indexed repo is stored under
@ -527,7 +529,11 @@ export async function runFullAnalysis(
processes: pipelineResult.processResult?.stats.totalProcesses,
},
undefined,
{ skipAgentsMd: options.skipAgentsMd, noStats: options.noStats },
{
skipAgentsMd: options.skipAgentsMd,
skipSkills: options.skipSkills,
noStats: options.noStats,
},
);
} catch {
// Best-effort — don't fail the entire analysis for context file issues

View file

@ -137,6 +137,101 @@ describe('generateAIContextFiles', () => {
}
});
it('does not create .claude/skills/gitnexus/ when skipSkills is true (#742)', async () => {
// Regression guard for #742. The --skip-skills flag must prevent
// installSkills() from writing the 6 standard skill dirs into the
// analyzed repo. Per-test tmpdir so we start from a known-clean
// slate — the shared tmpDir from beforeAll may already contain
// .claude/skills/gitnexus/ from an earlier test.
const skipDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gn-ai-ctx-skip-skills-'));
const skipStorage = path.join(skipDir, '.gitnexus');
await fs.mkdir(skipStorage, { recursive: true });
try {
const stats = { nodes: 50, edges: 100, processes: 5 };
const result = await generateAIContextFiles(
skipDir,
skipStorage,
'TestProject',
stats,
undefined,
{ skipSkills: true },
);
expect(result.files).toContain('.claude/skills/gitnexus/ (skipped via --skip-skills)');
await expect(
fs.access(path.join(skipDir, '.claude', 'skills', 'gitnexus')),
).rejects.toThrow();
} finally {
await fs.rm(skipDir, { recursive: true, force: true });
}
});
it('writes nothing when both skipAgentsMd and skipSkills are true (--index-only, #742)', async () => {
// Regression guard for #742. analyzeCommand() resolves --index-only
// into BOTH skipAgentsMd=true and skipSkills=true. This test pins
// the resolved-flag combination so a future regression that drops
// either guard fails here. Per-test tmpdir for the same reason as
// the skipSkills test above.
const idxDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gn-ai-ctx-index-only-'));
const idxStorage = path.join(idxDir, '.gitnexus');
await fs.mkdir(idxStorage, { recursive: true });
try {
const stats = { nodes: 50, edges: 100, processes: 5 };
const result = await generateAIContextFiles(
idxDir,
idxStorage,
'TestProject',
stats,
undefined,
{ skipAgentsMd: true, skipSkills: true },
);
expect(result.files).toContain('AGENTS.md (skipped via --skip-agents-md)');
expect(result.files).toContain('CLAUDE.md (skipped via --skip-agents-md)');
expect(result.files).toContain('.claude/skills/gitnexus/ (skipped via --skip-skills)');
await expect(fs.access(path.join(idxDir, 'AGENTS.md'))).rejects.toThrow();
await expect(fs.access(path.join(idxDir, 'CLAUDE.md'))).rejects.toThrow();
await expect(fs.access(path.join(idxDir, '.claude', 'skills', 'gitnexus'))).rejects.toThrow();
} finally {
await fs.rm(idxDir, { recursive: true, force: true });
}
});
it('omits standard skill references from AGENTS.md/CLAUDE.md when skipSkills is true (#742)', async () => {
// The skills routing table in AGENTS.md/CLAUDE.md points agents at
// .claude/skills/gitnexus/*/SKILL.md files installed by installSkills().
// When --skip-skills suppresses that install but AGENTS.md/CLAUDE.md
// are still written, the routing table must NOT name files that don't
// exist — otherwise every agent load incurs 6 failed reads and the
// routing instructions are worthless. Per-test tmpdir so the assertions
// are not contaminated by a CLAUDE.md from an earlier test.
const noStdDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gn-ai-ctx-no-std-skills-'));
const noStdStorage = path.join(noStdDir, '.gitnexus');
await fs.mkdir(noStdStorage, { recursive: true });
try {
const stats = { nodes: 50, edges: 100, processes: 5 };
await generateAIContextFiles(noStdDir, noStdStorage, 'TestProject', stats, undefined, {
skipSkills: true,
});
const content = await fs.readFile(path.join(noStdDir, 'CLAUDE.md'), 'utf-8');
expect(content).not.toContain('gitnexus-exploring/SKILL.md');
expect(content).not.toContain('gitnexus-impact-analysis/SKILL.md');
expect(content).not.toContain('gitnexus-debugging/SKILL.md');
expect(content).not.toContain('gitnexus-refactoring/SKILL.md');
expect(content).not.toContain('gitnexus-guide/SKILL.md');
expect(content).not.toContain('gitnexus-cli/SKILL.md');
// The load-bearing imperative sections must still ship — only the
// routing rows are conditional.
expect(content).toContain('## Always Do');
expect(content).toContain('## Never Do');
expect(content).toContain('gitnexus://repo/TestProject/context');
} finally {
await fs.rm(noStdDir, { recursive: true, force: true });
}
});
it('preserves manual AGENTS.md and CLAUDE.md edits when skipAgentsMd is enabled', async () => {
const stats = { nodes: 42, edges: 84, processes: 3 };
const agentsPath = path.join(tmpDir, 'AGENTS.md');

View file

@ -0,0 +1,27 @@
import { describe, it, expect } from 'vitest';
import { shouldGenerateCommunitySkillFiles } from '../../src/cli/analyze.js';
describe('shouldGenerateCommunitySkillFiles (#742 / PR 1485)', () => {
it('is false when --index-only is set even if --skills and pipelineResult are present', () => {
expect(shouldGenerateCommunitySkillFiles({ skills: true, indexOnly: true }, { ok: true })).toBe(
false,
);
});
it('is false when pipelineResult is missing', () => {
expect(shouldGenerateCommunitySkillFiles({ skills: true, indexOnly: false }, null)).toBe(false);
expect(shouldGenerateCommunitySkillFiles({ skills: true }, undefined)).toBe(false);
});
it('is true when --skills is set, pipeline exists, and not index-only', () => {
expect(
shouldGenerateCommunitySkillFiles({ skills: true, indexOnly: false }, { communities: [] }),
).toBe(true);
expect(shouldGenerateCommunitySkillFiles({ skills: true }, { x: 1 })).toBe(true);
});
it('is false when --skills is omitted', () => {
expect(shouldGenerateCommunitySkillFiles({ indexOnly: false }, { x: 1 })).toBe(false);
expect(shouldGenerateCommunitySkillFiles(undefined, { x: 1 })).toBe(false);
});
});

View file

@ -17,9 +17,41 @@ describe('--skip-git CLI flag', () => {
expect(helpOutput).toContain('--skip-git');
expect(helpOutput).toContain('--skip-agents-md');
expect(helpOutput).toContain('--skip-skills');
expect(helpOutput).toContain('--index-only');
expect(helpOutput).not.toContain('--no-git');
});
it('warns when --index-only overrides --skills (PR 1485)', () => {
// `--index-only` suppresses the post-index skill step that `--skills`
// would otherwise trigger. Without an explicit warning, the user sees a
// pipeline re-index complete and silently no skill files written — the
// silent-contradiction case flagged in PR 1485 review.
const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gn-index-only-skills-'));
const gitnexusHome = fs.mkdtempSync(path.join(os.tmpdir(), 'gn-index-only-skills-home-'));
// Make tmpDir a git repo so analyze accepts it without --skip-git.
execSync('git init', { cwd: tmpDir, stdio: 'ignore' });
fs.writeFileSync(path.join(tmpDir, 'a.ts'), 'export const a = 1;\n');
const env = {
...process.env,
HOME: gitnexusHome,
GITNEXUS_HOME: gitnexusHome,
GITNEXUS_LBUG_EXTENSION_INSTALL: 'never',
};
try {
const output = execSync(
`node "${cliPath}" analyze "${tmpDir}" --index-only --skills --skip-agents-md`,
{ encoding: 'utf8', timeout: 60000, env },
);
expect(output).toContain('--index-only overrides --skills');
} finally {
fs.rmSync(tmpDir, { recursive: true, force: true });
fs.rmSync(gitnexusHome, { recursive: true, force: true });
}
});
it('rejects non-git folder without --skip-git', () => {
const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gn-no-git-'));
fs.writeFileSync(path.join(tmpDir, 'test.ts'), 'export const x = 1;');