# Mykg

> Run mykg knowledge-graph commands inside Claude Code from one slash command `/mykg`. The user describes intent in natural language (extract, append, 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…

- **Type:** Skill
- **Install:** `agentstack add skill-senolisci-mykg-mykg`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [SenolIsci](https://agentstack.voostack.com/s/senolisci)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [SenolIsci](https://github.com/SenolIsci)
- **Source:** https://github.com/SenolIsci/mykg/tree/main/src/mykg/data/skills/mykg

## Install

```sh
agentstack add skill-senolisci-mykg-mykg
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```bash
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:
   1. **Literal session name.** User typed `--session ` 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 ` → 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 `, `/mykg extract `, `/mykg extract more from `, "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 . 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.
4. **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.

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** yes
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** yes

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-senolisci-mykg-mykg
- Seller: https://agentstack.voostack.com/s/senolisci
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.