SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsyzr-llm-workspace-management

yzr-llm-workspace-management

Agents & models

View repository

Updated 10-16 06:23

About this skill

LLM Workspace Management

Per 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 yzr-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 workflows + boundaries
  • references/workspace-spec.md—workspace root's 9 categories of filesownership + skill reading contract + security constraints (the complete toml schema is SSOT by the CLI code; the spec does not provide an authoritative definition)
  • scripts/——check_workspace_fixtures.py（Executable source of truth for CLI artifact compliance: fixtures consistency check, outputs repair actions; the spec document is its description, and when inconsistent, the detector prevails. Also used as the migrate detector. standalone, Python 3.7+; end-to-end test test_check_workspace_fixtures.py）

When not to use

"When to use / not applicable" is already in the frontmatter description (including trigger words); the body does not repeat it. This section only supplementsway out：

  • a single wiki's ingest / query / lint(including cross-page Q&A within a single wiki)—go through yzr-llm-wiki-management 's corresponding workflow
  • workspace / wiki metadata CRUD(init / add / remove / config / enter / model ...)— go through the workspace CLI (e.g. llmw); this skill neither calls nor runs it on your behalf
  • cloud collaboration wikis(Notion / Confluence / Outline Wiki / GitHub Wiki)—go through yzr-outline-wiki
  • one-off document generation—just use the normal file-writing workflow

Input / Output

Information required 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 time
Operation type User natural language scan / query / link / lint / migrate
Query scope (query only) User natural language or explicitly specified wiki names If unspecified, go through global INDEX routing

Operation artifacts

  • scan → write <workspace>/INDEX.md(human-readable overview) + <workspace>/STATS.md(structured statistics), write to disk per spec §4 / §5 Write to disk
  • query → give the answer in the conversation (with per-wiki citations); optionally write <workspace>/cross_queries/<slug>.md (requires user confirmation before archiving; format see spec §7）
  • link → append cross-wiki links to the source / entity pages of each wiki involved in cross-wiki references (go through yzr-llm-wiki-management 's ingest workflow; do not write wiki files directly)
  • lint → write <workspace>/LINT.md(most recent report, overwritten on each lint; format see spec §8) + summarize in the conversation
  • migrate → run scripts/check_workspace_fixtures.py to output a drift report (each finding includes a repair action); after repairs per the report, the agent's workspace is compatible with the latest spec; see §6 Migrate for details

Execution principles / boundaries

Boundaries with the workspace CLI

This skill does not call the workspace CLI. Reason:

  1. The workspace CLI only reads/writes three metadata files + starts a session—this skill reads workspace.toml / wiki_metadata.toml directlywhich is more reliable than parsing CLI output (CLI output is meant for humans, and 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 its authority
  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. Rely on a one-way DAG (acyclic): both this skill and the workspace CLI rely only on spec files to align on the contract (workspace-spec.md is owned by this repo; wiki-spec.md is in the yzr-llm-wiki-management repo); this skill does notdirectly depend on the workspace CLI's code or binary; at runtime it only delegates to yzr-llm-wiki-management(next section)

Boundaries with yzr-llm-wiki-management

This skill delegates single-wiki operations to yzr-llm-wiki-management: a single wiki's ingest / query / lint / writing cross-wiki links to a wiki's source page are all handed off to its corresponding process—this skill does not directlyedit <wiki>/wiki/**(maintaining invariants such as keeping log.md in sync within the wiki and required frontmatter). This skill does workspace-layerwork: scan aggregation / route routing / cross-wiki synthesis and comparison / cross-wiki link suggestions / workspace lint / cross-wiki memory.

File ownership (invariant, mandatory)

File / directory Maintainer This skill's stance
<workspace>/workspace.toml workspace CLI Read-only (for migration exceptions see §6)
<workspace>/CLI 内部配置 *.toml(model registry / runtime, etc.) workspace CLI Read-only (not even read; unaware of model configuration)
<workspace>/.gitignore workspace CLI Read-only (for migration exceptions see §6)
<workspace>/AGENTS.md（SSOT） User (copies the SSOT template during CLI init) Read-only (schema constitution; confirm with the user before changing; for migration exceptions see §6);scope = cross-wiki, not loaded within wiki subdirectories (see the "Loading scope boundaries" subsection)
<workspace>/CLAUDE.md(thin shell) User (copies the thin-shell template during CLI init) Read-only (for migration exceptions see §6);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 creates 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,...} yzr-llm-wiki-management Write through it
<wiki>/MEMORY/ yzr-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 thin-shell template during CLI init) read-only
<wiki>/raw/ User read-only

Full ownership table see spec §1。violating ownership = bug: this skill writing workspace.toml is overreach; CLI writing INDEX.md is overreach; skill writing <workspace>/AGENTS.md / CLAUDE.md is overreach (user constitution; for spec upgrade migration exceptions see §6 + spec §17.2).MEMORY cross-boundary confusion: this skill forbidswriting <wiki>/MEMORY/, single-wiki memory belongs to yzr-llm-wiki-management; likewise forbidden to write cross-wiki observations into single-wiki MEMORY—per spec §9 scope boundary。

Workflow / Steps

0. Startup check

Every time you enter this skill:

  1. Locate workspace path:$LLMW_WORKSPACE → default ~/yzr_llm_wiki_workspace → ask interactively (same as the "Information required at startup" table)
  2. Verify <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 cross-wiki MEMORY index: when working at the workspace root, via <workspace>/AGENTS.md 's @MEMORY/MEMORY.md import it loads automatically; when working outside the root / natively reading AGENTS.md without expanding @ 's agent → explicitly Read <$LLMW_WORKSPACE>/MEMORY/MEMORY.md to fill in (for the loading mechanism see spec §9.1）
  4. Load scope boundary：<workspace>/AGENTS.md / CLAUDE.md only constrainscross-wiki work—when the agent cwd is inside the <wiki>/ subdirectory and instead runs yzr-llm-wiki-management , this skill's discipline (including cross-wiki MEMORY)does nottake over; <wiki>/AGENTS.md single-wiki discipline applies (the template has a scope declaration at the top; beware MEMORY scope confusion: workspace MEMORY/ = cross-wiki,<wiki>/MEMORY/ = single-wiki; log write ownership: in-wiki ingest writes <wiki>/wiki/, not workspace-level INDEX / STATS)
  5. Do notautomatically run scan—wait for the user to give an operation intent

1. Scan / refresh-index

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

Flow：

  1. Version comparison(spec §14): read <workspace>/workspace.toml 's templates_version, if the workspace_spec component does not match this skill's metadata.workspace_spec_version → warn the user "workspace spec is behind (X → Y), recommend going through §6 Migrate first" (non-blocking; only continue scanning after the user confirms)
  2. Read <workspace>/workspace.toml to get the [wikis] registry
  3. For each wiki:
    • read <wiki>/wiki_metadata.toml(maintained by CLI)
    • read <wiki>/AGENTS.md §0 (to get the topic name) + §I (to get the boundaries)
    • read <wiki>/wiki/index.md(existing content + section 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 + count, do not read content)
    • read <wiki>/wiki/log.md 's last entry to get last activity
    • read <wiki>/MEMORY/ to get the memory files count (filenames only)
  4. Read <workspace>/MEMORY/MEMORY.md index (to know existing cross-wiki memories, for query routing / scan report references); aggregate by wiki name in alphabetical order, write <workspace>/INDEX.md(format see spec §5）+ <workspace>/STATS.md (format see spec §6）
  5. Atomic write (POSIX tmp + fsync + rename）
  6. Report in conversation: "Refreshed INDEX.md / STATS.md, 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 clearly outdated (does not cover newly added wikis), then prompt to scan first.

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 it belongs 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 + annotate the source of each wiki
compare "Compare A and B" / "the difference between A and B" Read wiki-A and wiki-B's wiki/index.md → query both sides → diff-style comparison
local "Only look at wiki X" / "look up Y in X" Go through yzr-llm-wiki-management query (single wiki)

Decision rules：

  • User explicitly specifies 1 wiki → local
  • User explicitly specifies 2 wikis and includes "compare / difference / similarities and differences" → compare
  • 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 yzr-llm-wiki-management query flow SKILL.md's "whether to archive" principle. Archive location:

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

When the archived body cites upstream volatile facts, pass the perception test (drift point avoidance)—for the rule SSOT see yzr-llm-wiki-management 's references/ingest-workflow.md §7 "Stability of citations in the body".

3. Link (cross-wiki cross-references)

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

Flow：

  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 across wikis (compare using description) 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 involved wiki, call yzr-llm-wiki-management 's ingest flow to update the corresponding entity / concept page—append a "cross-wiki references" section, with reference paths relative to the workspace root (e.g. [huawei_storage wiki 的 storage-architecture](../huawei_storage_wiki/wiki/concepts/storage-architecture.md)）

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

4. Lint (workspace level)

Trigger: "workspace lint" / "workspace health check" / periodically (e.g., incidentally on each scan).

Process：

  1. workspace-level deterministic checks(agent inline / later split into scripts):
    • Duplicate entities across wikis (pairs with the same name + different slug)
    • Broken cross-wiki links (cross_queries/*.md's sources path does not exist;<wiki>/wiki/** 's ../<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 thematically overlapping wikis 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: linting within a single wiki (duplicate entities / missing frontmatter / contradictory claims, etc.) —hand off to yzr-llm-wiki-management
  4. Output: write <workspace>/LINT.md(format see spec §8) + report in the conversation

When not to lint: user only asks a query → do not lint; 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 accumulating.

Write / do not write: only writecross-wiki perspectiveexperience (associations / organization preferences / lint patterns / synthesis experience); single-wiki pitfalls, cross-wiki synthesis answers themselves, and one-off observations are allnotwritten—for the complete list and scope boundaries see spec §9.3。

Process：

  1. Identify a cross-wiki observation worth accumulating
  2. Scope self-check—confirm it is a cross-wiki perspective (not involving only a single wiki)
  3. Determine the entry form(full vs short entry, for the criteria see spec §9): full entry → go to steps 4-6; short entry → go directly to step 6
  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 (frontmatter 5 required fields:title / type(use workspace-memory） / created / updated / tags; recommended wikis array + description）
    • already exists → Edit update body + updated field,created Keep original value
  6. Sync MEMORY.md one index line: full entry - <slug> — 一句话摘要 → [正文](<slug>.md); short entry - <一句话事实>(no link, no corresponding .md; index permanently reachable via AGENTS.md @ @ import) — omission = unreadable next time, lint memory-not-indexed fallback
  7. Do notAppend INDEX.md(MEMORY is an agent-private entry point) nordo notwrite log.md (no workspace-level log)

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 rebuild it (skip if it already exists), and only appends when writing cross-wiki experience *.md + sync 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>/MEMORY/ingest-special-char-pitfall.md(single-wiki experience)
"The user prefers putting 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 synthesis answer: compare the performance optimization methods of A and B" <workspace>/cross_queries/perf-compare-a-b.md(the answer itself, not a memory)

6. Migrate (upgrade workspace spec)

Trigger: "upgrade workspace / migrate / check workspace version / old format / spec upgrade"; or §1 scan version comparison finds templates_version is behind.

Responsibility split：scripts/check_workspace_fixtures.py = Detector(scan only, no fixes; outputs a drift report with fix actions; fix scope is always ≤ 4 structural files, no plan file is written, zero intermediate artifacts — see spec §17.3); agent (this section) = fixer, executes the report's fix actions, and ownership openings strictly follow spec §17.2; migration SSOT = report fix actions (to_action self-contained) + spec §17。 do notwrite INDEX.md / STATS.md / LINT.md — migration is not a scan / lint event.

Process：

  1. Run detection：

    python3 scripts/check_workspace_fixtures.py "$LLMW_WORKSPACE"

    --json for programmatic consumption; exit code 0 all pass / 1 has error / 2 runtime error (checklist see spec §17.3）

  2. dry-run report(always run by default): group by finding and list "which files need changes, based on the report's fix.to_action"; ask the user: apply all / apply some / view list only

  3. Execute fixes(after user confirmation, apply item by item per fix.type , with specific actions based on the report's fix.to_action ):

    • workspace-fix-agents-md-resync— extract §6 4 variables (fallback H1 + prose lines when there is no "current configuration" table) → render workspace-agents-md-template.md (use target value for version) → diff the old file, adjudicate each extra local customization with the user (move to MEMORY/ or discard) → Write overwrite (do notdo partial Edit)
    • workspace-fix-agents-version— single Edit version line (if resync reports the same, handle it together via resync, do not do this step)
    • workspace-fix-claude-md-resync / -create— render per workspace-claude-md-template.md Write (only variable {{WORKSPACE_DISPLAY_NAME}}）
    • workspace-fix-gitignore-skeleton——Single Edit to fill missing sections / managed-block rules (untoucheduser-defined rules)
    • workspace-fix-memory-index-init / -skeleton——Create verbatim according to canonical/memory-index.md character by character, or a single Edit to fill the skeleton (untouched ## 索引 growing entries under )
    • workspace-fix-templates-version——Finalize Edit workspace.toml of templates_version single field (the rest untouched)

  4. Verification: rerun the script——finish with 0 errors; if findings remain, report the residue + escalate to a human

  5. Do nottrigger each wiki's migrate——when the report shows the wiki_spec component laggingpromptthe user to go wiki by wiki through yzr-llm-wiki-management §5 Migrate (cross-skill delegation, do not run it on their behalf)

Boundaries：

  • Do notmodify the CLI's internal config toml (model registry, etc.) / any file inside each <wiki>/ any file within
  • Do notrun scan / query / link / lint during the migration process (keep responsibilities single-purpose)
  • templates_version 's wiki_spec component is only displayed, not compared——Each wiki's version is managed by yzr-llm-wiki-management , and this skill does not read sibling skills' versions
  • current > skill(workspace newer than SKILL):Do notblock; warn the user to upgrade the SKILL repo;Do notmodify the workspace

Reference examples

Example 1: Cross-wiki comprehensive Q&A

User: "What records are there 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. Delegate to yzr-llm-wiki-management to huawei_storage_wiki to run query: "RAID"
  4. Get the answer (with source page references), give it to the user in the conversation, attaching "only involves 1 wiki, whether to archive to huawei_storage_wiki/wiki/syntheses/raid-overview.md？"
  5. User confirms → go through yzr-llm-wiki-management to write the synthesis page + log entry

Example 2: Cross-wiki comparison

User: "huawei_storage_wiki and test wiki, what are the differences in performance optimization?"

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

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. Return: "huawei_storage_wiki 's topic is storage, irrelevant;test wiki's topic is test, also irrelevant; suggest creating a new wiki (llmw wiki --name=llm-inference add ...）"
  4. Do notautomatically run llmw wiki add——tell the user to run the CLI command

Reference files

  • Required reading：references/workspace-spec.md——ownership of the 9 categories of files at the workspace root + skill reading contract (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 wrapper <workspace>/CLAUDE.md see workspace-claude-md-template.md
  • must-read：yzr-llm-wiki-management SKILL.md's references/wiki-spec.md—— directory / frontmatter / naming constraints within a single wiki (followed by this skill when operating on a wiki)
  • delegation target：yzr-llm-wiki-management SKILL.md—— single-wiki ingest / query / lint / memory workflow (this skill's single-wiki operations are delegated to it)
  • CLI documentation: workspace CLI repo (command llmw, repo path is maintained externally by the user)——this skill does not directly call, but the user's init / add / remove / config / enter / model ... command references this