mirror of
https://github.com/Ar9av/obsidian-wiki.git
synced 2026-09-14 20:36:34 +08:00
Arnav
8b5859d0f8
* fix(cache): lock and atomically write .manifest.json update_source was a plain read-modify-write with no mutual exclusion, so any two overlapping writers lost an entry silently: the second reader's snapshot predated the first writer's write. This fires in three real configurations — batch-plan fan-out dispatching parallel ingest subagents, the Dockerized server writing a vault a local skill is also using, and a scheduled daily-update overlapping an interactive session. Reproduced with 12 concurrent update_source processes against one vault: 6 of 12 entries recorded before, 12 of 12 after. Writes now take an advisory lockfile and replace the manifest atomically via a temp file plus os.replace. O_CREAT|O_EXCL rather than fcntl because this ships on Windows. Hashing stays outside the lock — it can take seconds on a large source tree and nothing in the manifest depends on it. The contention test spawns real subprocesses; a single-process test cannot observe this race. * feat(trust): flag illegal lifecycle transitions in lint The lifecycle field is a state machine, but nothing enforced its edges. Ledger entries now record the lifecycle at review time, giving lint a baseline to compare the current frontmatter against. Only edges that are illegal for every possible sequence of unobserved intermediate states are flagged: falling back to draft (only ingest sets draft) and exiting archived (terminal). draft -> verified is deliberately not flagged — ledger snapshots are sparse, so a legitimate intermediate reviewed may simply never have been recorded, and flagging that pair would fire on valid history. Additive: entries predating the lifecycle field carry no baseline and are skipped, so existing vaults behave identically until their next trust-record. Owner-extended lifecycle states never match the illegal pairs, so the check degrades to a no-op rather than firing on states it does not understand. Warns by default, fails under --strict-trust, matching how the surrounding trust checks were already staged. * feat(wiki-status): add vault equilibrium mode The maintenance skills each optimize one shared vault for a different objective, so any of them can undo another's work and no single skill reporting clean means maintenance is done. Equilibrium mode runs every maintenance audit in report-only form and reports whether any skill still has a pending change. The vault is converged only when all of them propose nothing. It also detects oscillation via a snapshot in _insights.md, alongside the existing GRAPH_SNAPSHOT: a skill whose pending count keeps returning after being driven to zero is being reversed by another skill, and the vault can never settle. Reported, never auto-fixed — resolving it is a decision about whose objective wins. Pending moves are attributed back to their manifest source, so a source that repeatedly produces pages needing repair surfaces as a suggestion to review its source_quality. Report-only; the owner still decides through the existing trust flow. Skill-only, no Python: lint already emits JSON counts and the other three audits are LLM passes. * docs: document manifest write safety, lifecycle checks, and equilibrium Covers the advisory lock and atomic manifest write (including the parallel-run contract), the illegal_lifecycle_transitions check and why draft -> verified is excluded, and equilibrium mode in the architecture feature list.
6.9 KiB
6.9 KiB
Skills Reference
Everything lives in .skills/. Each skill is a markdown file the agent reads when your request matches its description — there's no runtime, no plugin system, no registration step.
Slash commands (/skill-name) work in Claude Code, Cursor, Windsurf, and most CLI agents. Everywhere else, just describe what you want.
Setup & vaults
| Skill | What it does | Slash command |
|---|---|---|
wiki-setup |
Initialize the vault structure, index, log, and Obsidian config | /wiki-setup |
wiki-switch |
Manage multiple named vault profiles; switch the active one | /wiki-switch <name> |
daily-update |
Daily maintenance cycle — source freshness, index rebuild, hot cache | /daily-update |
Feeding the brain
| Skill | What it does | Slash command |
|---|---|---|
wiki-ingest |
The catch-all. Distills documents, PDFs, chat exports, logs, transcripts, images, and URLs into wiki pages | /wiki-ingest |
wiki-capture |
Save the current conversation as a wiki note; --quick stages findings to _raw/ in under 60 seconds |
/wiki-capture |
wiki-update |
Sync the current project's knowledge into the vault — works from any repo | /wiki-update |
wiki-research |
Autonomous multi-round web research, filed straight into the vault | /wiki-research [topic] |
wiki-history-ingest |
Unified router for agent history ingest | /wiki-history-ingest <agent> |
claude-history-ingest |
Mine ~/.claude conversations and memories (Claude Code + desktop) |
/claude-history-ingest |
codex-history-ingest |
Mine ~/.codex sessions and rollout logs |
/codex-history-ingest |
hermes-history-ingest |
Mine ~/.hermes memories and sessions |
/hermes-history-ingest |
openclaw-history-ingest |
Mine ~/.openclaw MEMORY.md and sessions |
/openclaw-history-ingest |
copilot-history-ingest |
Mine ~/.copilot CLI session history |
/copilot-history-ingest |
pi-history-ingest |
Mine ~/.pi/agent/sessions JSONL history |
/pi-history-ingest |
wiki-agent |
Topic-first ingest from one agent's raw history | /wiki-claude, /wiki-codex, /wiki-hermes, /wiki-openclaw, /wiki-copilot, /wiki-pi |
Asking the brain
| Skill | What it does | Slash command |
|---|---|---|
wiki-query |
Answer questions from the vault with citations. Tiered — reads summaries before page bodies | /wiki-query |
wiki-narrate |
Render a cited briefing, plain-language explanation, or progressive lecture from a topic | /wiki-narrate <topic> |
wiki-digest |
Newsletter-style summary of what you learned over a day, week, or month | /wiki-digest [period] |
wiki-context-pack |
Produce a token-bounded context slice for a downstream agent or skill | /wiki-context-pack |
memory-bridge |
Browse and diff knowledge by which AI tool wrote it | /memory-bridge |
Finding past sessions
These two build a retrieval index over your raw agent sessions. They write a sidecar at ~/.claude/session-brain/ and never touch the vault. See Session Brain.
| Skill | What it does | Slash command |
|---|---|---|
session-brain |
Build and maintain a topic graph over your agent session history | /session-brain |
session-search |
Find a past session by topic and load its context into the current conversation | /wiki-sessions <topic> |
Ingest vs. retrieve. If you want knowledge preserved as permanent vault pages, use
wiki-history-ingest. If you want to find the session where something happened, use these.
Maintaining the brain
| Skill | What it does | Slash command |
|---|---|---|
wiki-status |
What's ingested, what's pending, the delta — plus vault-shape insights (hubs, bridges, clusters) and an equilibrium check across the maintenance skills | /wiki-status |
wiki-lint |
Find broken links, orphans, stale content, contradictions, missing frontmatter | /wiki-lint |
wiki-dedup |
Identity resolution — merge pages covering the same concept under different names | /wiki-dedup |
cross-linker |
Auto-discover unlinked mentions and weave them into the graph with [[wikilinks]] |
/cross-linker |
tag-taxonomy |
Enforce a consistent tag vocabulary across every page | /tag-taxonomy |
wiki-synthesize |
Discover and fill synthesis gaps across concepts | /wiki-synthesize |
wiki-stage-commit |
Review and promote staged pages when WIKI_STAGED_WRITES=true |
/wiki-stage-commit |
wiki-rebuild |
Archive the vault, rebuild from scratch, or restore a previous archive | /wiki-rebuild |
Seeing & moving the brain
| Skill | What it does | Slash command |
|---|---|---|
graph-colorize |
Color-code the Obsidian graph view by tag, category, or visibility | /graph-colorize |
wiki-dashboard |
Create dynamic Obsidian Bases dashboard views | /wiki-dashboard |
wiki-export |
Export the graph to JSON, GraphML, Neo4j Cypher, Postgres SQL, interactive HTML, or an OKF bundle | /wiki-export |
wiki-import |
Import a graph.json export or an OKF markdown bundle into the current vault |
/wiki-import |
obsidian-layout-adjustment |
Restyle Obsidian via CSS snippets — tabs, sidebars, graph panes, note surfaces | — |
Extending the framework
| Skill | What it does | Slash command |
|---|---|---|
llm-wiki |
The core pattern and architecture reference every other skill defers to | /llm-wiki |
skill-creator |
Create, edit, and eval new skills | /skill-creator |
vault-skill-factory |
Turn a cluster of mature vault pages into a portable "digital expert" skill | /vault-skill-factory |
impl-validator |
Validate an implementation against its stated goal | /impl-validator |
Recommended companion: Obsidian Skills by Kepano
This framework handles the knowledge-management workflow — ingest, query, lint, rebuild. For Obsidian format mastery, install kepano/obsidian-skills alongside it. Optional, but it improves output quality:
| Skill | What it adds |
|---|---|
obsidian-markdown |
Correct Obsidian-flavored syntax — wikilinks, callouts, embeds, properties |
obsidian-bases |
Create and edit .base files (database-like views of notes) |
json-canvas |
Create and edit .canvas files (visual mind maps, flowcharts) |
obsidian-cli |
Interact with a running Obsidian instance via CLI |
defuddle |
Extract clean markdown from web pages — less noise, fewer tokens during ingest |
npx skills add kepano/obsidian-skills
Both projects follow the same Agent Skills spec, so they coexist in the same .skills/ directory with no conflicts.
Writing your own
See Contributing → Adding a new skill, or just ask:
"Create a skill that generates weekly summaries from my journal entries"
skill-creator walks you through drafting, testing, and refining it in .skills/.