diff --git a/graphify/skill-agents.md b/graphify/skill-agents.md index f09e56ca8..d142c0eb6 100644 --- a/graphify/skill-agents.md +++ b/graphify/skill-agents.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/graphify/skill-amp.md b/graphify/skill-amp.md index f09e56ca8..d142c0eb6 100644 --- a/graphify/skill-amp.md +++ b/graphify/skill-amp.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/graphify/skill-claw.md b/graphify/skill-claw.md index 612da0090..a1c94b30a 100644 --- a/graphify/skill-claw.md +++ b/graphify/skill-claw.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/graphify/skill-codex.md b/graphify/skill-codex.md index d826d76e6..fc17ddb1a 100644 --- a/graphify/skill-codex.md +++ b/graphify/skill-codex.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/graphify/skill-copilot.md b/graphify/skill-copilot.md index 612da0090..a1c94b30a 100644 --- a/graphify/skill-copilot.md +++ b/graphify/skill-copilot.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/graphify/skill-droid.md b/graphify/skill-droid.md index ada369b7d..8471dbd81 100644 --- a/graphify/skill-droid.md +++ b/graphify/skill-droid.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/graphify/skill-kilo.md b/graphify/skill-kilo.md index 9b043233f..710eef983 100644 --- a/graphify/skill-kilo.md +++ b/graphify/skill-kilo.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/graphify/skill-kiro.md b/graphify/skill-kiro.md index 612da0090..a1c94b30a 100644 --- a/graphify/skill-kiro.md +++ b/graphify/skill-kiro.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/graphify/skill-opencode.md b/graphify/skill-opencode.md index 5cb74e81a..5b1d02eb2 100644 --- a/graphify/skill-opencode.md +++ b/graphify/skill-opencode.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/graphify/skill-pi.md b/graphify/skill-pi.md index 612da0090..a1c94b30a 100644 --- a/graphify/skill-pi.md +++ b/graphify/skill-pi.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/graphify/skill-trae.md b/graphify/skill-trae.md index 2037e539f..34b9b4177 100644 --- a/graphify/skill-trae.md +++ b/graphify/skill-trae.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/graphify/skill-vscode.md b/graphify/skill-vscode.md index 9002650e4..7038108c0 100644 --- a/graphify/skill-vscode.md +++ b/graphify/skill-vscode.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/graphify/skill-windows.md b/graphify/skill-windows.md index 1246089d5..1d722f201 100644 --- a/graphify/skill-windows.md +++ b/graphify/skill-windows.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -188,16 +188,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -239,7 +237,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' '@ | & (Get-Content graphify-out\.graphify_python) - ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/graphify/skill.md b/graphify/skill.md index 612da0090..a1c94b30a 100644 --- a/graphify/skill.md +++ b/graphify/skill.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/tests/test_skillgen.py b/tests/test_skillgen.py index ab6f94474..83885b9da 100644 --- a/tests/test_skillgen.py +++ b/tests/test_skillgen.py @@ -149,6 +149,57 @@ def test_extraction_states_no_api_key_required_for_every_host(): f"{a.path}: no-key clarity is not hoisted above the GEMINI tip" +@pytest.mark.parametrize( + "platform", + [p for p in gen.load_platforms().values() if p.core == "core"], + ids=lambda p: p.key, +) +def test_issue4061_workflow_respects_documented_skips(platform): + """Shared-core hosts must not override their fast paths with absolutes.""" + core = gen.render(platform)[0].content + assert "Do not skip steps." not in core + assert "Skip a step only where explicitly instructed" in core + assert "skip Steps 1–5 entirely" in core + assert "A plain local path skips this step." in core + assert "Skip this step entirely if `detect` returned zero `video` files." in core + + semantic = core.split("#### Part B - Semantic extraction", 1)[1].split( + "**Step B1", 1 + )[0] + assert "MANDATORY:" not in semantic + assert "you are doing this wrong" not in semantic + assert "one subagent per chunk" in semantic + assert "5-10x faster" in semantic + assert "Skip dispatch when the Part B fast path applies" in semantic + assert "a host that cannot dispatch subagents" in semantic + assert "First write an empty semantic file" in semantic + + +@pytest.mark.parametrize( + "platform", + [p for p in gen.load_platforms().values() if p.core == "core"], + ids=lambda p: p.key, +) +def test_issue4061_credentials_have_one_accurately_scoped_note(platform): + """Consolidate fallback guidance without changing #2513 provider routing.""" + core = gen.render(platform)[0].content + extraction = core.split("### Step 3 - Extract entities and relationships", 1)[1].split( + "#### Part A", 1 + )[0] + credential_notes = [ + line for line in extraction.splitlines() + if line.startswith("> ") and "API key" in line and not line.startswith("> Tip:") + ] + assert len(credential_notes) == 1 + note = credential_notes[0] + assert "Never ask the user for one, and never block on one." in note + assert "cannot dispatch subagents" in note + assert "headless CLI supports other configured providers" in note + assert "No other API keys are read" not in extraction + assert "graphify does **not** read" not in extraction + assert "extract those inline yourself" in note + + def test_references_contain_no_core_pipeline_content(): """No reference fragment may duplicate the core build pipeline.""" _, refs = _claude_artifacts() diff --git a/tools/skillgen/expected/graphify__skill-agents.md b/tools/skillgen/expected/graphify__skill-agents.md index f09e56ca8..d142c0eb6 100644 --- a/tools/skillgen/expected/graphify__skill-agents.md +++ b/tools/skillgen/expected/graphify__skill-agents.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/tools/skillgen/expected/graphify__skill-amp.md b/tools/skillgen/expected/graphify__skill-amp.md index f09e56ca8..d142c0eb6 100644 --- a/tools/skillgen/expected/graphify__skill-amp.md +++ b/tools/skillgen/expected/graphify__skill-amp.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/tools/skillgen/expected/graphify__skill-claw.md b/tools/skillgen/expected/graphify__skill-claw.md index 612da0090..a1c94b30a 100644 --- a/tools/skillgen/expected/graphify__skill-claw.md +++ b/tools/skillgen/expected/graphify__skill-claw.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/tools/skillgen/expected/graphify__skill-codex.md b/tools/skillgen/expected/graphify__skill-codex.md index d826d76e6..fc17ddb1a 100644 --- a/tools/skillgen/expected/graphify__skill-codex.md +++ b/tools/skillgen/expected/graphify__skill-codex.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/tools/skillgen/expected/graphify__skill-copilot.md b/tools/skillgen/expected/graphify__skill-copilot.md index 612da0090..a1c94b30a 100644 --- a/tools/skillgen/expected/graphify__skill-copilot.md +++ b/tools/skillgen/expected/graphify__skill-copilot.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/tools/skillgen/expected/graphify__skill-droid.md b/tools/skillgen/expected/graphify__skill-droid.md index ada369b7d..8471dbd81 100644 --- a/tools/skillgen/expected/graphify__skill-droid.md +++ b/tools/skillgen/expected/graphify__skill-droid.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/tools/skillgen/expected/graphify__skill-kilo.md b/tools/skillgen/expected/graphify__skill-kilo.md index 9b043233f..710eef983 100644 --- a/tools/skillgen/expected/graphify__skill-kilo.md +++ b/tools/skillgen/expected/graphify__skill-kilo.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/tools/skillgen/expected/graphify__skill-kiro.md b/tools/skillgen/expected/graphify__skill-kiro.md index 612da0090..a1c94b30a 100644 --- a/tools/skillgen/expected/graphify__skill-kiro.md +++ b/tools/skillgen/expected/graphify__skill-kiro.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/tools/skillgen/expected/graphify__skill-opencode.md b/tools/skillgen/expected/graphify__skill-opencode.md index 5cb74e81a..5b1d02eb2 100644 --- a/tools/skillgen/expected/graphify__skill-opencode.md +++ b/tools/skillgen/expected/graphify__skill-opencode.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/tools/skillgen/expected/graphify__skill-pi.md b/tools/skillgen/expected/graphify__skill-pi.md index 612da0090..a1c94b30a 100644 --- a/tools/skillgen/expected/graphify__skill-pi.md +++ b/tools/skillgen/expected/graphify__skill-pi.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/tools/skillgen/expected/graphify__skill-trae.md b/tools/skillgen/expected/graphify__skill-trae.md index 2037e539f..34b9b4177 100644 --- a/tools/skillgen/expected/graphify__skill-trae.md +++ b/tools/skillgen/expected/graphify__skill-trae.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/tools/skillgen/expected/graphify__skill-vscode.md b/tools/skillgen/expected/graphify__skill-vscode.md index 9002650e4..7038108c0 100644 --- a/tools/skillgen/expected/graphify__skill-vscode.md +++ b/tools/skillgen/expected/graphify__skill-vscode.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/tools/skillgen/expected/graphify__skill-windows.md b/tools/skillgen/expected/graphify__skill-windows.md index 1246089d5..1d722f201 100644 --- a/tools/skillgen/expected/graphify__skill-windows.md +++ b/tools/skillgen/expected/graphify__skill-windows.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -188,16 +188,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -239,7 +237,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' '@ | & (Get-Content graphify-out\.graphify_python) - ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/tools/skillgen/expected/graphify__skill.md b/tools/skillgen/expected/graphify__skill.md index 612da0090..a1c94b30a 100644 --- a/tools/skillgen/expected/graphify__skill.md +++ b/tools/skillgen/expected/graphify__skill.md @@ -56,7 +56,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -160,16 +160,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -211,7 +209,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` diff --git a/tools/skillgen/fragments/core/core.md b/tools/skillgen/fragments/core/core.md index 412535088..ae6f0f3e4 100644 --- a/tools/skillgen/fragments/core/core.md +++ b/tools/skillgen/fragments/core/core.md @@ -53,7 +53,7 @@ If no path was given, use `.` (current directory). Do not ask the user for a pat If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. -Follow these steps in order. Do not skip steps. +Run the steps in order. Skip a step only where explicitly instructed. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) @@ -113,16 +113,14 @@ Skip this step entirely if `detect` returned zero `video` files. When the corpus This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). -> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. +> **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM or key; for a code-only corpus, run Part A and follow Part B's fast path to write the empty semantic file before Part C. This skill's semantic extraction route uses Gemini when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. The headless CLI supports other configured providers through `graphify.llm.detect_backend()`; this skill's Gemini check does not select those providers. On a host that dispatches subagents, follow Part B for uncached docs, papers, and images. On a host that cannot dispatch subagents, extract those inline yourself. Proceed without waiting for credentials. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. -> **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. - -**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** +**When Part B needs host-agent dispatch and the host supports subagents, start the semantic subagents and Part A (AST) in the same message. Both can run simultaneously since they operate on different file types. Respect Part B's fast path and cache check before dispatching. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. @@ -164,7 +162,7 @@ Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],' " ``` -**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** +**For host-agent semantic extraction, use the platform's dispatch mechanism described in Step B2 (the Agent tool on Claude Code), one subagent per chunk; parallel dispatch is 5-10x faster than reading files yourself. Skip dispatch when the Part B fast path applies or a configured Gemini backend handles semantic extraction. On a host that cannot dispatch subagents, use the inline fallback described above.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json`