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.
110 lines
6.9 KiB
Markdown
110 lines
6.9 KiB
Markdown
# Skills Reference
|
|
|
|
Everything lives in [`.skills/`](../.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](session-brain.md).
|
|
|
|
| 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**](https://github.com/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 |
|
|
|
|
```bash
|
|
npx skills add kepano/obsidian-skills
|
|
```
|
|
|
|
Both projects follow the same [Agent Skills spec](https://agentskills.io/specification), so they coexist in the same `.skills/` directory with no conflicts.
|
|
|
|
## Writing your own
|
|
|
|
See [Contributing → Adding a new skill](contributing.md#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/`.
|