mykg — single slash command, intent-driven CLI dispatcher

This skill is the agent-mode driver for mykg. The user types /mykg <free text> describing what they want; the skill parses the intent, assembles the matching mykg CLI command (with live --help as ground truth for flags), confirms expensive actions, and executes. For LLM-bearing subcommands (extract-graph), it then drives the inbox/outbox watch loop. For synchronous subcommands (walkthrough, approve-schema, parse-docs), it shells out and reports. For the read-only query verb, it prefers MCP tools when the mykg MCP server is online, falling back to reading session files directly when MCP is unavailable, with the mykg query CLI as a last-resort fallback.

The pipeline code, the orchestrator, all prompts, all 12 pipeline steps, and the inbox/outbox contract are unchanged. This skill only changes how mykg is invoked from inside Claude Code.

---

Read before answering — discipline rule

Before answering any domain question about the corpus this project's mykg sessions cover, read the latest session's graph files first. Your training data is not grounded in this project's source documents; the graph is. Use /mykg query <question> (Stage 4d below) to do this — it returns the relevant nodes/edges/notes into your context so you can answer from them rather than guessing.

This rule applies to every /mykg query … invocation and to every domain question asked outside the skill when the project's CLAUDE.md carries the managed mykg-section block (installed by mykg init --profile agent-claude-code).

---

Default behaviour — fresh session unless told otherwise

The default is to create a NEW session for every extract-graph invocation. Pass no --session flag to mykg extract-graph and let mykg auto-create a fresh timestamped session under mykg_sessions/.

Only reuse an existing session when the user explicitly signals it. Explicit signals are any of:

• The verbs resume, continue, redo, append, sync, reconcile, approve, walkthrough.
• A direct reference: "the last session", "the existing session", "the same session", or a literal session name (typed as --session <name> or "session ").
• A flag whose semantics require a session: --append, --sync, --update, --from-step <step>.
• A subcommand that inherently targets a completed session: approve-schema, walkthrough.

For anything else — including bare /mykg <dir>, /mykg extract <dir>, /mykg extract more from <dir>, "extract this folder" — pass NO --session flag. Words like "more", "again", "now", "next" are NOT explicit signals; they trigger a fresh session like every other plain extract command.

Never auto-detect-most-recent purely because a previous skill turn produced a session. The previous-turn signal only matters when the current user message also contains one of the explicit signals above.

When in doubt, default to fresh and surface the choice in the Stage 2 confirmation.

---

When to invoke — intent examples

Trigger this skill whenever the user types /mykg <anything>. Map the intent to a mykg CLI command using the table below as a guide; for anything not covered, fall back to the closest match and confirm before running.

User typed	Skill should run
/mykg extract this folder (when cwd contains md files)	mykg extract-graph . (fresh session — no --session)
/mykg ./docs	mykg extract-graph ./docs (legacy positional alias — fresh session — no --session)
/mykg extract ./docs	mykg extract-graph ./docs (fresh session — no --session)
/mykg extract more from ./more_docs	mykg extract-graph ./more_docs (fresh session — "more" is NOT an explicit reuse signal; this is just another extract)
/mykg extract ./docs with human review	mykg extract-graph ./docs --review (fresh session — no --session)
/mykg append the new notes in ./docs	mykg extract-graph ./docs --append --session <auto-detect-most-recent> (explicit reuse via append; NEW files only — see --sync below)
/mykg sync the graph with ./docs	mykg extract-graph ./docs --update --session <auto-detect-most-recent> ("sync"/"reconcile"/"update" → --update, the shorthand for --append --sync)
/mykg pick up my edits in ./docs	mykg extract-graph ./docs --update --session <auto-detect-most-recent> (--update/--sync, not plain --append — since D58 a modified file is only re-extracted under --sync)
/mykg remove deleted files from the graph	mykg extract-graph <folder> --update --session <auto-detect-most-recent>
/mykg append and grow schema from ./docs	mykg extract-graph ./docs --append-with-grow-schema --session <auto-detect-most-recent> (explicit reuse via append; locked Pass 1 runs over changed files to expand the schema)
/mykg expand the schema with new docs in ./docs	mykg extract-graph ./docs --append-with-grow-schema --session <auto-detect-most-recent> ("expand schema" → --append-with-grow-schema)
/mykg resume the last session	mykg extract-graph --session <most-recent> (explicit reuse via resume the last session)
/mykg approve the schema	mykg approve-schema --session <most-recent> (session-only subcommand)
/mykg make a walkthrough	mykg walkthrough --session <most-recent> (session-only subcommand)
/mykg make a walkthrough for 2026-06-02T17-30-00	mykg walkthrough --session 2026-06-02T17-30-00 (literal session name)
/mykg convert pdfs in ./inbox to ./md	mykg parse-docs --input ./inbox --output ./md (no session concept)
/mykg fetch https://example.com	mykg fetch-web https://example.com (no session concept)
/mykg fetch https://example.com into ./my_output_dir (user names the output folder)	mykg fetch-web https://example.com --output ./my_output_dir (no session concept)
/mykg fetch https://example.com and extract	mykg fetch-web https://example.com, then on success mykg extract-graph <printed output dir> (fresh session) — chained two-step intent
/mykg download the github repo SenolIsci/mykg	mykg fetch-web https://github.com/SenolIsci/mykg (GitHub URL → clone path, no session concept)
/mykg fetch these urls: urls.txt into ./mykg_web_fetch/batch	mykg fetch-web --url-list urls.txt --output ./mykg_web_fetch/batch (no session concept)
/mykg fetch these urls: <url1> <url2> <url3> ... (URLs typed inline, not a file path)	write each URL on its own line to a temp file mykg_urls.txt (in cwd), then mykg fetch-web --url-list mykg_urls.txt --output ./mykg_web_fetch/batch (no session concept)
/mykg fetch these urls: <url1> <url2> <url3> ... and extract (URLs typed inline)	same temp-file step as above, then mykg fetch-web --url-list mykg_urls.txt --output ./mykg_web_fetch/batch; on success, for each per-seed output subdir reported in the manifest, run mykg extract-graph <subdir> (fresh session per subdir) — chained multi-seed intent
/mykg query who is Alice	read-only — Stage 4d on the latest session; vault-first because the phrasing names an entity (wiki-style)
/mykg query what does the wiki say about <topic>	read-only — Stage 4d on the latest session; vault path (obsidian_vault/); word "wiki" is explicit
/mykg query most connected node in the knowledge graph	read-only — Stage 4d on the latest session; jsonl path (nodes.jsonl + edges.jsonl); words "knowledge graph" / "most connected" are structural
/mykg query which entities link Alice to Bob	read-only — Stage 4d on the latest session; jsonl path; relationship-traversal question
/mykg query <free text> on session <name>	read-only — Stage 4d on the named session instead of the latest
/mykg from-step orphan_connect on the last session	mykg extract-graph --session <most-recent> --from-step orphan_connect (explicit reuse via the last session + --from-step)
/mykg rerun orphan-connect from scratch on the last session	mykg extract-graph --session <most-recent> --from-step orphan_connect_fullsweep (explicit reuse via the last session)
/mykg redo orphans but keep what we already confirmed	mykg extract-graph --session <most-recent> --from-step orphan_connect_incremental (explicit reuse via redo — --from-step always operates on an existing session)
/mykg start mcp server	mykg mcp-serve --transport streamable_http --port 3100 (starts MCP server on HTTP; no session concept)
/mykg start mcp	mykg mcp-serve (starts MCP server with defaults from config; no session concept)
/mykg start mcp for session <name>	mykg mcp-serve --session <name> (MCP server for a specific session)
/mykg stop mcp	mykg mcp-serve --stop (stops a running HTTP MCP server)
/mykg mcp status	check if MCP server is running: ps aux | grep "mcp-serve" | grep -v grep
/mykg init	refuse: "Run mykg init from a shell — it is interactive."
/mykg merge sessions A and B	refuse: "Skill support for mykg merge-graphs is planned in a follow-up. Run from a shell."

---

Discovering CLI flags

The skill MUST NOT hand-code flag tables. The single source of truth is the live --help output. Once at the top of each skill turn, run the help commands for the subcommands you might dispatch and cache the output in shell variables for the rest of the turn:

EXTRACT_HELP=$(uv run mykg extract-graph --help 2>&1)
WALKTHROUGH_HELP=$(uv run mykg walkthrough --help 2>&1)
APPROVE_HELP=$(uv run mykg approve-schema --help 2>&1)
PARSE_HELP=$(uv run mykg parse-docs --help 2>&1)
FETCH_HELP=$(uv run mykg fetch-web --help 2>&1)

Use these cached values to:

• validate that any flag the user mentioned actually exists,
• complain if the user typed a non-existent flag,
• automatically pick up new flags (e.g. tomorrow a --use-cache flag is added) with zero skill changes.

---

MCP configuration — ensure .mcp.json exists

At the start of every skill turn, check whether the project has a .mcp.json file that configures the mykg MCP server for Claude Code. If it does not exist, ask the user for approval before creating it:

I noticed this project doesn't have a .mcp.json file to configure the mykg
MCP server for Claude Code. The MCP server provides 14 structured read-only
tools (search, neighbors, shortest path, hub nodes, subgraph queries, etc.)
that are faster and more precise than manual grep/Read for graph queries.

Shall I create .mcp.json with this content?

{
  "mcpServers": {
    "mykg": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/project",
        "run",
        "mykg",
        "mcp-serve"
      ]
    }
  }
}

This tells Claude Code to start `mykg mcp-serve` as an MCP subprocess,
making the `mcp__mykg__*` tools available in this session. The server
auto-discovers the latest session on startup.

If the user approves, write the file. If the user declines, proceed without it — the skill falls back to manual grep/Read in Stage 4d as before.

If .mcp.json already exists but does not contain a mykg server entry, ask the user whether to add one (preserve the existing entries). If it already has a mykg entry, do nothing.

Do not create .mcp.json without user approval. This file affects the Claude Code session and the user must consent.

---

Stage 1 — parse intent

From the user's /mykg <free text> message extract:

1. Verb — extract / append / approve / walkthrough / parse / fetch / download / resume / init / merge / query → maps to a CLI subcommand, a refusal, or the read-only file-read path (query). Fetch / download (URL or GitHub repo) maps to fetch-web — no session, same category as parse-docs.
2. Input dir — the path the user named, or . if they said "this folder", or absent for session-only commands (including query).
3. Session — default: do not pass --session at all so mykg auto-creates a fresh timestamped session. Only override the default when the current user message contains an explicit reuse signal (see "Default behaviour" above). Resolution order:
   1. Literal session name. User typed --session <name> or "session " → use that exact name.
   2. Explicit reuse verb / phrase. User said one of: resume, continue, redo, append, approve, walkthrough, query, "the last session", "the existing session", "the same session" → auto-detect the most-recent session: list $SESSIONS_DIR (read sessions_dir from mykg_config.yaml, default mykg_sessions), sort by mtime, pick newest.
   3. Reuse-implying flag. User specified --append or --from-step <step> → auto-detect-most-recent (these flags only make sense against an existing session).
   4. Session-only verb. Verb is approve-schema, walkthrough, or query → auto-detect-most-recent. (query is read-only and always operates against an existing session.)
   5. Otherwise. Do NOT pass --session. mykg creates a fresh session. This is the path for bare /mykg <dir>, /mykg extract <dir>, /mykg extract more from <dir>, "extract this folder", etc.
   6. Reuse required but missing. If rules 2/3/4 fire but no session exists under $SESSIONS_DIR, fail clearly: "No existing sessions under <SESSIONS_DIR>. Run /mykg extract <dir> first to create one."

Never auto-detect-most-recent purely because a previous skill turn produced a session. The previous-turn memory only matters when the current user message also contains one of the explicit signals in rules 1-4. A bare /mykg ./more_docs after a prior session must still create a fresh session. 4. Flags — anything the user named that maps to a flag the cached --help confirms (--review, --append, --sync, --update, --from-step <step>, --workers <N>, --obsidian-vault, --base-schema, --freeze-schema, --thesaurus, --verbose, --confidence-agg, --append-with-grow-schema, etc.). Forward verbatim.

extract-graph without --append or --from-step does not need a pre-existing session — it auto-creates one.

--sync — reconciling modifications and deletions (D58)

--append adds; --sync reconciles. Four supported combinations:

Command	New files	Modified files	Deleted files	Schema
--append	extracted	warn only	warn only	frozen
--append-with-grow-schema	extracted	warn only	warn only	may grow
--append --sync (= --update)	extracted	re-extracted	removed	frozen
--append-with-grow-schema --sync	extracted	re-extracted	removed	may grow

--update is shorthand for --append --sync — prefer it when the user's intent is "make the graph match the folder". --sync on its own requires --append (a ClickException otherwise). Detection always runs, so a plain --append that finds modified or deleted files logs a warning naming them and pointing at --sync — the graph is left untouched.

⚠️ Behaviour change: before D58, plain --append re-extracted modified files. It no longer does. If a user says their edits "aren't showing up", the answer is almost always --sync.

Intent triggers — use --update (or --append --sync) when the user says: "update", "sync", "reconcile", "remove deleted", "pick up my edits", "my changes aren't showing", "make the graph match the folder", "clean up files I deleted".

Nothing to reconcile is free. With no modifications and no deletions, --append --sync degrades to exactly plain --append — no prune, no shard eviction, no extra LLM calls. It is safe to leave in a script permanently.

Deletion accuracy depends on pass2.prep_mode. Exact under per_file or batch_chunks + batch_per_file: true. On the shipped default a co-batched sibling may retain over-attributed nodes (the pre-existing D53 limitation) — mention this if the user reports a node that "won't go away".

Multiple source folders. Each folder appended to a session is registered with its own mirror subtree, so two crawls that both produce index.md no longer overwrite each other. --sync is scoped to the folder named on the command line: reconciling one folder can never delete another's files.

--append-with-grow-schema — expanding the schema incrementally (D52)

Use case: you have an existing session with an induced schema (e.g. Project, Person, Organization) and you add new documents that introduce entity types or relationships the current schema doesn't cover (e.g. a tech-stack document that describes technologies). Plain --append freezes the schema — Pass 1 is skipped, so new concept types and properties are never induced, and the new documents are extracted against the old vocabulary. --append-with-grow-schema solves this: it implies --append and runs a locked Pass 1 over the changed files only, allowing the LLM to propose new concepts and properties while preserving everything already in the schema. Since D58 "changed files" means NEW files unless --sync is also passed — add --sync when the new vocabulary lives in a document the user edited rather than added.

How it works:

1. The session's existing schema.ttl is auto-loaded as a locked base schema — existing classes and properties cannot be renamed, removed, or re-parented.
2. Pass 1 runs over only the changed files (not the whole corpus), so cost is O(changed files).
3. The LLM may add new concepts, new properties, or new attributes to existing types. It cannot modify locked entries.
4. Pass 2 extracts the new files against the grown schema. If new properties were added, a surgical back-fill may re-extract old chunks that contain nodes of the new properties' domain/range types (configurable via append.grow_schema_backfill_top_k_chunks_per_type, default 10; set 0 to disable).
5. All downstream steps (assemble, orphan pass, validate) re-run over the full corpus so the graph stays consistent.

When the schema delta is empty (the new documents don't introduce new types), the run collapses to a plain --append — no wasted LLM cost. And when there is nothing to reconcile at all, the locked Pass 1 is skipped entirely (zero LLM calls) rather than dispatched over the whole corpus.

Intent triggers — use --append-with-grow-schema when the user says any of: "grow schema", "expand schema", "grow the schema", "expand the vocabulary", "add new types", "learn new concepts from", "update the schema with". The flag implies --append (no need to pass both). --append-with-grow-schema is mutually exclusive with --from-step and --base-schema.

Confirmation note: in Stage 2, mention that locked Pass 1 will run (costs LLM calls) vs plain --append which skips Pass 1:

About to run: uv run mykg extract-graph ./docs --append-with-grow-schema --session 2026-06-21T11-22-38

This will run a locked Pass 1 over the new files (LLM calls) to expand the schema,
then extract. Plain --append would skip Pass 1 and keep the schema frozen.

Reply "yes" to run, or "just append" to skip schema growth.

--freeze-schema — bring-your-own-schema extraction

Use case: you have a complete ontology (RDFS or OWL TTL) and want the LLM to extract instances against exactly those types — no LLM-invented concepts, no surprise properties. Pass 1 is skipped entirely, saving 3 LLM calls.

mykg extract-graph ./docs --base-schema ontology.ttl --freeze-schema

Rules:

• --freeze-schema requires --base-schema <path>. If the user says "freeze schema" without providing a TTL file, ask for it.
• Mutually exclusive with --append and --append-with-grow-schema.
• The output graph will only contain the concept types and relationship properties declared in the TTL — nothing else.

Intent triggers — use --freeze-schema when the user says any of: "freeze schema", "frozen schema", "use this schema exactly", "no LLM schema", "skip schema induction", "extract with my ontology only", "strict schema", "use only my types". Always pair with --base-schema.

fetch-web flags and special cases

fetch-web is a no-session verb, same category as parse-docs — Stage 1 item 3's session-resolution logic never fires for it. Forward --url-list, --output, --max-pages, --max-depth, --strategy, --download-assets/--no-download-assets, --delay, --concurrency, --no-robots, --force, -v/--verbose verbatim when the user names them, validated against $FETCH_HELP.

--output: when the user names a destination folder ("into ./X", "save to ./X", "output ./X"), pass --output ./X verbatim — do not rewrite or normalize the path beyond what the user typed. When the user doesn't name one and the intent is single-seed, omit --output and let the CLI default (./mykg_web_fetch/<domain>/) apply. For --url-list (including the inline-tempfile case below), --output is required by the CLI — if the user didn't name one, default to ./mykg_web_fetch/batch.

Inline URL list → temp file. If the user pastes multiple URLs directly in the message (not a path to an existing file), --url-list can't be used as-is — it requires a file. Write each URL on its own line to mykg_urls.txt (cwd), one URL per line, no comments/blank lines needed since the skill controls the content, then pass --url-list mykg_urls.txt. Mention the temp file's path to the user in the Stage 5 report so they know it was created (it is not auto-deleted — leaving it is harmless and lets the user re-run/edit the list).

Special --from-step values for the orphan-connect step

--from-step accepts every pipeline step name (preprocess, ingest, pass1, schema_validate, human_review, schema_flatten, pass2, normalize_names, assemble, orphan_score, orphan_connect, validate_graph) plus two aliases specific to the orphan-connection step. When the user describes intent that maps to either of these, pick the alias rather than bare orphan_connect:

--from-step value	Semantics	Pick when the user says
orphan_connect	Equivalent to orphan_connect_fullsweep — bare form is the default.	"rerun orphan connect", "redo the orphan pass" (with no qualifier)
orphan_connect_fullsweep	Deletes orphan_connections.json, orphan_log.json, schema_gap_proposals.json + all downstream outputs. The orphan-connect step recomputes every group from scratch — every orphan is re-sent to the LLM. Expensive but gives a clean redo.	"rerun from scratch", "fullsweep", "clean redo", "schema changed since last run", "model upgrade"
orphan_connect_incremental	Deletes downstream outputs but preserves orphan_connections.json + orphan_log.json. The step loads the prior file as a seed, treats every orphan endpoint already in a confirmed edge as "resolved", and only sends the remaining uncovered groups to the LLM. Old confirmations are merged with new ones. Cheap and additive.	"redo orphans but keep what we have", "additive", "only do the new ones", "after --append"

If the user is ambiguous (e.g. "rerun orphans"), confirm in Stage 2 which one they want by presenting both options in one line.

Precondition — schema_max_restarts must be ≥ 1 for orphan_connect_fullsweep and orphan_connect_incremental to fully exercise the schema-gap auto-proposal loop. With schema_max_restarts: 0 (the shipped default in every profile) the aliases still execute, but the LLM is never asked to propose new schema properties for orphans the current schema cannot connect — those orphans remain orphans. The skill MUST handle this transparently via the auto-bump procedure below.