SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsllm-workspace-management

llm-workspace-management

Agents & models

View repository

Updated 10-16 08:10

About this skill

LLM Workspace Management

According to workspace-spec.md maintain alocal、multi-wiki workspace's "global view" and cross-wiki orchestration capability—a single wiki's ingest / query / lint still goes through llm-wiki-management SKILL.md skill. This skill stands above all wikis and does things that require cross-wiki judgment.

This skill provides three deliverables:

  • SKILL.md (this document)—the "constitution" of the workflow + boundaries
  • references/workspace-spec.md—the ownership of the 9 types of files at the workspace root + the authoritative schema definition (both the CLI and the skill write to disk / maintain according to it)
  • scripts/—solidify high-frequency deterministic tasks (does notinclude init—the workspace's init is handled by the workspace CLI)

When to use / not use

Use

  • The user says in conversation "summarize the content about X across all my wikis" / "look up X across wikis"
  • The user says in conversation "compare what wiki A and wiki B think about Y"
  • The user says in conversation "which wiki does this question belong to" / "which wiki should X go in"
  • The user says in conversation "scan the workspace" / "update INDEX.md" / "refresh the global view"
  • The user says in conversation "workspace-wide lint" / "workspace health check"
  • The user says in conversation "some entity in wiki A also exists in wiki B, add a cross-wiki link"
  • The user points to <workspace>/INDEX.md or <workspace>/STATS.md and says "this should be updated"
  • The user first mentions "I have multiple wikis / a workspace / a cross-wiki perspective"

Do not use

  • A single wiki's ingest / query / lint—goes through llm-wiki-management SKILL.md
  • workspace / wiki metadata CRUD(init / add / remove / config / enter / model add / remove / set-default)—goes through the workspace CLI (e.g. llmw）
  • Cloud collaboration wikis(Notion / Confluence / Outline Wiki / GitHub Wiki)—go through outline-wiki-upload(write / edit) / outline-wiki-search(search / read)
  • One-off document generation—directly use the ordinary file-writing workflow
  • Cross-page Q&A within a single wiki—goes through llm-wiki-management 's query workflow

Input / output

Information needed at startup

Information Source Notes
Workspace path $LLMW_WORKSPACE environment variable, or default ~/yzr_llm_wiki_workspace, or ask interactively The workspace CLI usually sets this variable at enter Set this variable beforehand
Operation type User natural language scan / query / link / lint
Query scope (query only) User natural language or explicitly specified wiki name If unspecified, use global INDEX routing

Operation output

  • scan → write <workspace>/INDEX.md(human-readable overview) + <workspace>/STATS.md(structured statistics), written to disk according to spec §4 / §5 persist to disk
  • query → give the answer in the conversation (with per-wiki citations); optionally persist <workspace>/cross_queries/<slug>.md (archiving requires user confirmation; for the format see spec §7）
  • link → append cross-wiki links to the source / entity pages of each wiki involved in the cross-wiki reference (go through the llm-wiki-management ingest flow; do not write wiki files directly)
  • lint → write <workspace>/LINT.md(most recent report, overwritten on each lint; for the format see spec §8) + summarize in the conversation

Execution principles / boundaries

Three-layer responsibility split

┌─────────────────────────────────────────────────────────────────┐
│ workspace CLI (如 llmw)                                          │
│   - 确定性元数据操作：init / add / remove / config / enter        │
│   - 写 workspace.toml / workspace_models.toml / .gitignore       │
│   - init 时按模板拷 AGENTS.md(SSOT)+CLAUDE.md(薄壳)            │
│   - 写 <wiki>/wiki_metadata.toml + wiki 仓骨架（按 wiki-spec）   │
│   - init 建 MEMORY/ + 写 MEMORY.md 索引（§9）                    │
│   - 不读不写 INDEX/STATS/LINT/cross_queries + MEMORY/*.md 经验   │
└─────────────────────────────────────────────────────────────────┘
                              ▲
                              │ 元数据 / 启动 session
                              │
┌─────────────────────────────────────────────────────────────────┐
│ llm-workspace-management (本 skill)                              │
│   - 跨 wiki 编排：scan / query (4 模式) / link / lint / memory   │
│   - 写 INDEX/STATS/LINT/cross_queries + MEMORY/*.md（同步索引）  │
│   - 写 <wiki>/wiki/** （通过 llm-wiki-management 委托）           │
│   - 不写 workspace.toml / workspace_models.toml / .gitignore      │
│   - 不写 <workspace>/AGENTS.md / CLAUDE.md（用户 schema）        │
│   - 不写 <wiki>/raw/                                              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ 单 wiki 内容操作
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ llm-wiki-management                                              │
│   - 单 wiki ingest / query / lint / memory                       │
│   - 写 <wiki>/wiki/{entities,concepts,sources,...}                │
│   - 不写 <wiki>/AGENTS.md（用户所有）                              │
│   - 不写 <wiki>/raw/                                              │
└─────────────────────────────────────────────────────────────────┘

Boundary with the workspace CLI

This skill does not call the workspace CLI. Reasons:

  1. The workspace CLI only reads / writes the three metadata files + starts a session—this skill reads workspace.toml / wiki_metadata.toml directlyis more reliable than parsing CLI output (CLI output is meant for humans; the text may change)
  2. This skill does not modify workspace.toml / wiki_metadata.toml—tell the user to run llmw wiki ..., and a human executes it. The CLI's metadata writes are user-driven decisions; the skill does not overstep
  3. The workspace CLI has already started the session via wiki enter (including the model overlay); within the session this skill only makes content-layer decisions and does not need to enter
  4. One-way DAG dependency: this skill → workspace-spec.md (authoritative contract); workspace CLI → workspace-spec.md; this skill does notdepend directly on the workspace CLI's code or binary

Boundary with llm-wiki-management

This skill delegates single-wiki operations to llm-wiki-management. Scenarios:

Scenario Delegation method
Ingest new material within a certain wiki Hand off to llm-wiki-management 's ingest flow
Query within a certain wiki Hand off to llm-wiki-management 's query flow
Lint within a certain wiki Hand off to llm-wiki-management 's lint flow
Write cross-wiki links to a certain wiki's source page Go through llm-wiki-management 's ingest update

What this skill does itself at the workspace layer: scan (aggregate) / route (routing) / cross-wiki synthesis / cross-wiki compare / cross-wiki link suggestion / workspace lint.

File ownership (invariant, mandatory)

File / directory Maintainer This skill's stance
<workspace>/workspace.toml workspace CLI read-only
<workspace>/workspace_models.toml workspace CLI read-only (not even read; unaware of model configuration)
<workspace>/.gitignore workspace CLI read-only
<workspace>/AGENTS.md（SSOT） User (copies the SSOT template during CLI init) read-only (schema constitution; confirm with the user before changing);scope = cross-wiki, not loaded within wiki subdirectories (see the "Loading scope boundary" subsection)
<workspace>/CLAUDE.md(thin shell) User (copies the thin-shell template during CLI init) read-only;scope = cross-wiki, not loaded within wiki subdirectories (same as above)
<workspace>/INDEX.md This skill write
<workspace>/STATS.md This skill write
<workspace>/cross_queries/ This skill Write
<workspace>/LINT.md This skill Write
<workspace>/MEMORY/ CLI init builds the skeleton (directory + MEMORY.md) + this skill CLI init writes the MEMORY.md index; the skill writes *.md experience + syncs the index
<wiki>/wiki_metadata.toml workspace CLI Read-only
<wiki>/wiki/{entities,concepts,sources,...} llm-wiki-management Write through it
<wiki>/wiki/MEMORY/ llm-wiki-management Write through it (single-wiki private memory)
<wiki>/AGENTS.md（SSOT） User (copies the SSOT template during CLI init) Read-only
<wiki>/CLAUDE.md(thin shell) User (copies the thin-shell template during CLI init) Read-only
<wiki>/raw/ User Read-only

See the full ownership table in spec §1。Violating ownership = bug: This skill writing workspace.toml is overreach; the CLI writing INDEX.md is overreach; the skill writing <workspace>/AGENTS.md / CLAUDE.md is overreach (user constitution).MEMORY cross-boundary confusion: this skill is forbiddento write <wiki>/wiki/MEMORY/, single-wiki memory belongs to llm-wiki-management; likewise forbidden to write cross-wiki observations to single-wiki MEMORY—follow spec §9 scope boundaries。

Cross-skill dependency graph (DAG, acyclic)

llm-workspace-management (本 skill)
  ├─→ references/workspace-spec.md (本 skill 自有)
  ├─→ references/wiki-spec.md (经 llm-wiki-management SKILL 仓引用)
  └─→ llm-wiki-management (运行时委托)

workspace CLI (llmw)
  ├─→ references/workspace-spec.md
  └─→ references/wiki-spec.md

llm-wiki-management
  └─→ references/wiki-spec.md (本 skill 自有)

This skill does not directly call the workspace CLI; the workspace CLI does not depend on this skill either. Both sides align on the contract through the spec file.

Workflow / steps

0. Startup check

Every time you enter this skill:

  1. Locate the workspace path:$LLMW_WORKSPACE → default ~/yzr_llm_wiki_workspace → ask interactively
  2. Verify that <workspace>/workspace.toml exists—if not, prompt the user "workspace hasn't been init'd yet, run llmw init to initialize" (do notrun it for the user)
  3. Load the cross-wiki MEMORY index: when working in the workspace root—Claude Code via the thin shell <workspace>/CLAUDE.md → @AGENTS.md automatically loads the SSOT,@MEMORY/MEMORY.md has the index inlined and resident in the session; other agents reading AGENTS.md (Qoder / Codex / Gemini CLI, etc.) natively read the SSOT; when working outside the root (the skill reads AGENTS.md via $LLMW_WORKSPACE ,@ does not auto-expand) → explicitly Read <$LLMW_WORKSPACE>/MEMORY/MEMORY.md to fill in the index, and know which cross-wiki memories already exist
  4. Load the scope-boundary determination(see the "Load scope boundaries" subsection below)—if the current agent cwd is inside some <wiki>/ subdirectory and switches to running llm-wiki-management, this skill's discipline (including the <workspace>/AGENTS.md content loaded in step 3)does nottake over that agent; instead <wiki>/AGENTS.md single-wiki discipline takes effect
  5. Do notautomatically run scan—wait for the user to give an operation intent

Load scope boundaries

<workspace>/AGENTS.md and <workspace>/CLAUDE.md only constraincross-wiki work (invoking llm-workspace-managementin the workspace root or an external cwd). When the agent cwd is in <wiki>/ or a deeper subdirectory and switches to calling llm-wiki-management , this skill does notautomatically load the workspace top-level AGENTS.md / CLAUDE.md—to avoid conflicting with <wiki>/AGENTS.md single-wiki discipline, especially the MEMORY scope boundary (workspace MEMORY/ = cross-wiki;<wiki>/MEMORY/ = single wiki), log / ingest write attribution (ingest within a wiki writes <wiki>/wiki/ and <wiki>/wiki/log.md, non-workspace-level INDEX.md / STATS.md). The @AGENTS.md cascade behavior differs across agents (Claude Code / Qoder / Codex / Gemini CLI); this skill does not implement the decision for any specific agent, and instead uniformly lets the agent decide through the boundary **"workspace skill discipline does not take over when working in a wiki subdirectory"**; <workspace>/AGENTS.md the template top self-contains a scope declaration for cascading parties to recognize.

1. Scan / refresh-index

Trigger: "scan the workspace" / "update INDEX.md" / the user says "the workspace should be refreshed".

Flow：

  1. Read <workspace>/workspace.toml to get the [wikis] registry
  2. For each wiki:
    • Read <wiki>/wiki_metadata.toml(maintained by CLI, schema v2)
    • Read <wiki>/AGENTS.md §0 (to get the topic name) + §一 (to get the boundaries)
    • Read <wiki>/wiki/index.md(existing content + paragraph skeleton)
    • Scan <wiki>/wiki/{entities,concepts,sources,comparisons,syntheses}/ to get page counts
    • Scan <wiki>/raw/ recursively to get the raw material count (only find + counting, do not read content)
    • Read the last entry of <wiki>/wiki/log.md to get last activity
    • Read <wiki>/wiki/MEMORY/ to get the memory files count (file names only)
  3. Read the <workspace>/MEMORY/MEMORY.md index (to know existing cross-wiki memory, for query routing / scan report references); aggregate by wiki name in alphabetical order, write <workspace>/INDEX.md(format see spec §4）+ <workspace>/STATS.md (format see spec §5）
  4. Atomic write (POSIX tmp + fsync + rename）
  5. Report in the conversation: "INDEX.md / STATS.md refreshed, X wikis, Y pages, Z raw materials"

When not to scan: the user only wants to do a query → use the existing INDEX.md first; if INDEX.md is missing or older than N days, then suggest scanning first.

Why not call a script: in the v1 stage the aggregation logic needs LLM judgment for "key entities" and "one-line summary", which a pure script cannot handle. Once it stabilizes, scripts/scan_workspace.py（v2 TODO）。

2. Query (cross-wiki Q&A)

Trigger: "summarize the content about X across all my wikis" / "compare A and B on Y" / "which wiki should X be looked up in".

4 modes(automatically determined by user intent + whether a wiki scope is specified):

Mode Trigger keywords Flow
route "which wiki should be looked up" / "which wiki does it belong to" Read INDEX.md → match by topic / tag / description → return 1–3 candidate wiki names + reasons
synthesis "summarize all" / "synthesize all wikis" / "cross-wiki summary" route → query each candidate wiki → merge + label the source for each wiki
compare "compare A and B" / "the difference between A and B" Read wiki/index.md of wiki-A and wiki-B → query both sides → diff-style comparison
local "only look at wiki X" / "look up Y in X" Go through llm-wiki-management query (single wiki)

Decision rules：

  • The user explicitly specifies 1 wiki → local
  • The user explicitly specifies 2 wikis and includes "compare / difference / similarities and differences" → compare
  • The user says "which one / where does it belong / where should it go" → route
  • Otherwise → synthesis

A good query must have a "whether to archive" step— refer to llm-wiki-management the "whether to archive" principle in the query workflow SKILL.md. Archive location:

  • The answer involvesa single wiki → archive to <wiki>/wiki/syntheses/<slug>.md(go through llm-wiki-management）
  • The answer involvesmultiple wikis → archive to <workspace>/cross_queries/<slug>.md(this skill writes directly, for the format see spec §7）

3. Link (cross-wiki cross-reference)

Trigger: "entity X in wiki A also exists in wiki B, add a link" / "scan for duplicate entities across wikis".

Workflow：

  1. Scan: for each wiki's wiki/entities/ + wiki/concepts/, extract all entity names (frontmatter title or filename slug)
  2. Deduplicate and aggregate: collect entities with the same name / similar meaning (compare using description) across wikis as candidate pairs
  3. Suggest: list the candidate pairs in the conversation and let the user choose which ones to add cross-wiki links to
  4. Write: after user confirmation, for each wiki involved, call llm-wiki-management 's ingest workflow to update the corresponding entity / concept page—append a "cross-wiki reference" section, with reference paths relative to the workspace root (e.g. [huawei_storage wiki 的 storage-architecture](../huawei_storage_wiki/wiki/concepts/storage-architecture.md)）

Invariant: this skill does not directlyedit <wiki>/wiki/**—always through llm-wiki-management 's ingest workflow (keeping the wiki's log.md in sync, frontmatter 5 required fields, invariants, etc.).

4. Lint (workspace-level)

Trigger: "workspace lint" / "workspace health check" / periodically (recommended after every N scans).

Workflow：

  1. Workspace-level deterministic checks(agent inline / later split into scripts):
    • Duplicate entities across wikis (pairs with the same name + different slugs)
    • Broken cross-wiki links (cross_queries/*.md's sources path does not exist;<wiki>/wiki/** in ../<another-wiki>/... path does not exist)
    • Unregistered wiki subdirectories ( <wiki>/AGENTS.md exists on disk but is not registered in workspace.toml)
    • Wikis registered in workspace.toml but not existing on disk (orphan registrations)
    • Whether the wiki lists in STATS.md and INDEX.md are consistent
    • MEMORY index consistency: scan <workspace>/MEMORY/*.md(excluding MEMORY.md), any file not listed in the MEMORY/MEMORY.md index → report memory-not-indexed(severity = info, aligned with the wiki-side lint-checklist §14)
  2. Semi-qualitative checks this skill performs：
    • Whether wikis with overlapping topics need to be merged
    • Whether the tag system is chaotic (same tag name with different meanings / same meaning with inconsistent tag naming)
  3. What this skill does not do: lint within a single wiki (duplicate entities / missing frontmatter / contradictory claims, etc.) —hand off to llm-wiki-management
  4. Output: write <workspace>/LINT.md(for the format see spec §8) + report in the conversation

When not to lint: if the user only asks a query → do not lint; if the user says "scan" → scan rather than lint.

5. Memory (cross-wiki agent private memory)

Trigger: proactively write when, during scan / query / link / lint, information is identified that iscross-wikiand worth capturing. Strict scope boundary(refer to spec §9.3）：

Write(cross-wiki perspective):

  • Cross-wiki associations—"X-type topics go in A wiki, Y-type go in B wiki"
  • User preferences for workspace organization—"I prefer splitting wikis by timeline rather than by topic"
  • Workspace-wide lint patterns—"the last N lints all reported a certain type of issue"
  • Cross-wiki synthesized experience—"this kind of question requires scanning first, then answering"

Do not write(to avoid overstepping):

  • Single-wiki pitfalls → belong to <wiki>/wiki/MEMORY/(delegate to llm-wiki-management）
  • The cross-wiki synthesized answer itself → belongs to <workspace>/cross_queries/
  • One-off observations → just chat, do not write to MEMORY

Process：

  1. Identify a cross-wiki observation worth capturing
  2. Scope self-check—confirm it is a cross-wiki perspective (not involving only a single wiki)
  3. Determine the entry form(in sync with the repository root MEMORY/ / wiki-side MEMORY):
    • Full entry—needs to explain "why do it this way" or "how to use it in the future" (including context / solution steps / how to avoid it in the future) → go to steps 4-7 full format
    • Short entry—pure reminder / single preference / no need for why + how → jump directly to step 6 short format
  4. Generate slug (kebab-case short title, e.g. user-prefers-time-based-wikis)—only needed for full entries
  5. Check whether the target MEMORY file already exists (full entries only):
    • Does not exist → Write new file (5 required frontmatter fields:title / type(use workspace-memory） / created / updated / tags; recommended wikis array + description）
    • Already exists → Edit update body + updated field,created keep the original value
  6. Sync MEMORY.md index with one line—choose the format according to the entry form:
    • Full entry:- <slug> — <一句话摘要> → [正文](<slug>.md)(the file from step 5 must exist; missing it = it cannot be read next time, lint memory-not-indexed as a fallback)
    • Short entry:- <一句话事实>(no link, no corresponding .md file; the index is imported by AGENTS.md @ import always resident so future sessions can reach it)
  7. Do notappend INDEX.md(MEMORY is an agent private entry point, it does not go into the workspace single entry point; butmustbe MEMORY.md listed in the index, see the previous step)
  8. Do not write log.md (MEMORY has no workspace-level log)

The MEMORY skeleton is not created by the skill：<workspace>/MEMORY/ directory + MEMORY.md index is created by CLI init (spec §9 §9.1); the skill does not recreate it (if it already exists, skip), only appends *.md when writing cross-wiki experience + syncs the index.

Clear boundary between MEMORY and single-wiki MEMORY：

Scenario Where to write
"wiki A's ingest always fails because raw/ contains special characters" <A>/wiki/MEMORY/ingest-special-char-pitfall.md(single-wiki experience)
"The user prefers to put everything storage-related in wiki A, and everything LLM-related in wiki B" <workspace>/MEMORY/user-storage-vs-llm-preference.md(cross-wiki preference)
"Cross-wiki synthesized answer: compare the performance optimization methods of A and B" <workspace>/cross_queries/perf-compare-a-b.md(the answer itself, not memory)

Reference examples

Example 1: Cross-wiki synthesized Q&A

User: "What records do I have about RAID across all my wikis?"

  1. skill reads <workspace>/INDEX.md → finds that huawei_storage_wiki 's description contains "storage"
  2. mode = synthesis(the user said "across all wikis")
  3. delegates llm-wiki-management to huawei_storage_wiki to query: "RAID"
  4. gets the answer (with source page references), gives it to the user in the conversation, with "only involves 1 wiki, whether to archive to huawei_storage_wiki/wiki/syntheses/raid-overview.md？"
  5. user confirms → goes through llm-wiki-management to write a synthesis page + log entry

Example 2: Cross-wiki comparison

User: "huawei_storage_wiki and test wikis, what's different about them in terms of performance optimization?"

  1. skill reads INDEX.md → both wikis are present
  2. mode = compare(two wikis + "different")
  3. delegates llm-wiki-management to both wikis to query: "performance optimization"
  4. compares the two answers, diffs by topic dimension (consensus / disagreement / unique to one side)
  5. asks whether to archive as <workspace>/cross_queries/storage-vs-test-perf.md(writes after user confirmation)

Example 3: Routing

User: "I just downloaded an LLM inference paper, which wiki should it go in?"

  1. skill reads INDEX.md + reads each wiki's description / tags
  2. mode = route
  3. returns: "huawei_storage_wiki 's topic is storage, not relevant;test wiki's topic is test, also not relevant; suggest creating a new wiki (llmw wiki --name=llm-inference add ...）"
  4. does notautomatically run llmw wiki add——tell the user to run the CLI command

Example 4: scan trigger

User: "scan my workspace"

  1. reads workspace.toml → 2 wikis
  2. reads each wiki's metadata + index.md + last entry of log.md + page counts
  3. writes <workspace>/INDEX.md(created on first run; overwritten on subsequent runs)
  4. writes <workspace>/STATS.md(same as above)
  5. conversation report: "INDEX.md / STATS.md refreshed——2 wikis, 0 pages total, 2 raw files total"

Reference files

  • Required reading：references/workspace-spec.md——workspace root ownership of the 9 file types + authoritative schema definition (including §4 AGENTS.md / CLAUDE.md + §9 MEMORY/)
  • Required reading：references/workspace-agents-md-template.md—— <workspace>/AGENTS.md(SSOT)'s canonical template byte-level gold standard (copied accordingly during CLI init); thin shell <workspace>/CLAUDE.md see workspace-claude-md-template.md
  • Required reading：llm-wiki-management SKILL.md's references/wiki-spec.md—— directory / frontmatter / naming constraints within a single wiki (this skill follows them when operating on a wiki)
  • Delegation target：llm-wiki-management SKILL.md—— single-wiki ingest / query / lint / memory workflow (this skill delegates its single-wiki operations to it)
  • CLI documentation: workspace CLI repo (command llmw, repo path maintained externally by the user)——this skill does not directly call, but the user's init / add / remove / config / enter / model ... command refers here