Mykg

mykg — single slash command, intent-driven CLI dispatcher

This skill is the agent-mode driver for mykg. The user types /mykg 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.

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

For anything else — including bare /mykg , /mykg extract , /mykg extract more from , "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 . 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 (explicit reuse via append) | | /mykg append and grow schema from ./docs | mykg extract-graph ./docs --append-with-grow-schema --session (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 ("expand schema" → --append-with-grow-schema) | | /mykg resume the last session | mykg extract-graph --session (explicit reuse via resume the last session) | | /mykg approve the schema | mykg approve-schema --session (session-only subcommand) | | /mykg make a walkthrough | mykg walkthrough --session (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 (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: ... (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: ... 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 (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 | 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 on session | 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 --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 --from-step orphan_connect_fullsweep (explicit reuse via the last session) | | /mykg redo orphans but keep what we already confirmed | mykg extract-graph --session --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 | mykg mcp-serve --session (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": "mykg",
        "args": ["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 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:
4. Literal session name. User typed --session or "session " → use that exact name.
5. 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.
6. Reuse-implying flag. User specified --append or --from-step → auto-detect-most-recent (these flags only make sense against an existing session).
7. 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.)
8. Otherwise. Do NOT pass --session. mykg creates a fresh session. This is the path for bare /mykg , /mykg extract , /mykg extract more from , "extract this folder", etc.
9. Reuse required but missing. If rules 2/3/4 fire but no session exists under $SESSIONS_DIR, fail clearly: "No existing sessions under . Run /mykg extract 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.

1. Flags — anything the user named that maps to a flag the cached --help confirms (--review, --append, --from-step , --workers , --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.

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

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.

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

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [SenolIsci](https://github.com/SenolIsci)
- **Source:** [SenolIsci/mykg](https://github.com/SenolIsci/mykg)
- **License:** MIT

Install and usage instructions live in the source repository linked above.