/mykg

name: mykg
description: Run mykg knowledge-graph commands inside Claude Code from one slash command `/mykg`. The user describes intent in natural language (extract, append, sync, resume, approve, walkthrough, parse-docs, fetch-web, query); the skill parses intent, builds the right `mykg` CLI command from the live `--help` output, confirms, runs it, and drives the inbox/outbox watch loop for LLM-bearing commands (extract-graph). For read-only queries, prefers MCP tools when the mykg MCP server is online, falling back to reading session files directly, with the `mykg query` CLI as a last-resort fallback. Ensures `.mcp.json` is configured (with user approval). Excludes `mykg init` (interactive shell command) and `mykg merge-graphs` (follow-up planning).

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**, **prune**, **drift**.
• A direct reference: **"the last session"**, **"the existing session"**, **"the same session"**, or a literal session name (typed as `--session <name>` or "session <name>").
• A flag whose semantics require a session: **`--append`**, **`--sync`**, **`--update`**, **`--from-step <step>`**.
• A subcommand that inherently targets a completed session: **`approve-schema`**, **`walkthrough`**, **`detect-schema-drift`**, **`prune-schema`**.

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-s