Use when the user asks for a usage review of their neuro-vault work over a period (e.g. "/analyze-vault-usage 7d", "review my last week of vault usage"). Runs the bundled nv-analytics CLI to compute deterministic aggregates over Claudian conversation records, critiques patterns, writes an actionable note to Inbox/neuro-vault-usage/YYYY-Www.md in the vault, and a visual HTML companion to /tmp.
How this skill is triggered — by the user, by Claude, or both
Slash command
/neuro-vault-analytics:analyze-vault-usageThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill orchestrates a single usage-review pass:
This skill orchestrates a single usage-review pass:
prompt.md./tmp.Invoke the CLI via the Bash tool (single command, no shell metacharacters):
node ${CLAUDE_PLUGIN_ROOT}/dist/cli.js --period <PERIOD> --format json
Where <PERIOD> is the argument the user supplied (default 7d if they did not).
Capture the stdout into a local variable. The output is an AnalyticsReport JSON
with three parallel buckets (vault / projects / total) and a per-project breakdown:
type AnalyticsReport = {
period: { startMs: number; endMs: number; label: string };
buckets: {
vault: BucketStats; // sessions started from inside the vault directory
projects: BucketStats; // sessions from external repos that called the vault MCP
total: BucketStats; // re-aggregated over the union
};
perProject: {
project: string;
decodedPath: string;
sessionsTotal: number;
sessionsVault: number;
topTools: { key: string; count: number }[];
uniqueTools: string[];
}[];
unusedTools: string[];
samples: (SampledSession & { bucket: 'vault' | 'projects'; project: string | null })[];
warnings: string[];
};
type BucketStats = {
sessionsTotal: number;
sessionsVault: number;
totalToolCalls: number;
avgToolCallsPerSession: number;
topTools: { key: string; count: number }[];
topSequences: { sequence: string[]; count: number; sessionIds: string[] }[];
largestResultTools: { key: string; avgSizeBytes: number }[];
stalePathErrors: {
sessionId: string;
searchToolCallTs: number;
readToolCallTs: number;
failedPath: string | null;
}[];
currentNoteAnchors: { key: string; count: number }[];
cacheHitDistribution: { p50: number; p90: number; mean: number };
subagentBudget: { mean: number; p95: number; max: number };
deadEndCount: number;
};
The CLI scans every directory under ~/.claude/projects/ by default; the
buckets.vault block is built from Claudian session metadata, while
buckets.projects is built from JSONL alone (no currentNote, no
context-window snapshot — see docs/architecture/claudian-records.md).
If the CLI fails (non-zero exit), surface its stderr to the user verbatim and stop.
Use the prompt template in ${CLAUDE_PLUGIN_ROOT}/skills/analyze-vault-usage/prompt.md. Substitute the JSON output into the <<REPORT_JSON>> placeholder, then think through the report and produce the note body.
Compute the destination path based on the actual window length (period.endMs - period.startMs):
Inbox/neuro-vault-usage/<YYYY-Www>.md, where YYYY-Www is the ISO week of period.endMs.Inbox/neuro-vault-usage/<YYYY-MM-DD-of-period.startMs>_to_<YYYY-MM-DD-of-period.endMs>.md.The note title # Usage analytics <label> mirrors the chosen filename label (2026-W17 or 2026-04-25_to_2026-04-26).
If the file already exists, overwrite it and tell the user one line: "Overwriting existing report for ."
Write the file via whichever Obsidian skill the user has available (e.g. obsidian:obsidian-cli). Frontmatter required:
---
type: review
created: <YYYY-MM-DD of period.endMs>
period_start: <YYYY-MM-DD of period.startMs>
period_end: <YYYY-MM-DD of period.endMs>
sessions_vault: <buckets.vault.sessionsTotal>
sessions_projects: <buckets.projects.sessionsTotal>
sessions_total: <buckets.total.sessionsTotal>
tags: [analytics, neuro-vault]
archived: false
---
ephemeral is intentionally not in tags — these notes are kept for cross-period diff. The explicit archived: false field is reserved for future lifecycle tooling.
After the MD note is in the vault, re-render the same analysis as a single-file HTML report in /tmp. The HTML is ephemeral and lives outside the vault by design.
Use the prompt template in ${CLAUDE_PLUGIN_ROOT}/skills/analyze-vault-usage/html-prompt.md. Substitute the same JSON output from Step 1 into the <<REPORT_JSON>> placeholder. The HTML prompt assumes the MD body from Step 3 is in your working memory — reuse the TL;DR, patterns, and suggestions prose verbatim where the HTML template asks for them.
Compute the cache-busting suffix once via the Bash tool:
node -e 'process.stdout.write(Date.now().toString(36).slice(-4))'
Capture stdout as <suffix> (4 base36 chars). Then write the rendered HTML via the Write tool to:
/tmp/nv-analytics-<label>-<suffix>.html
where <label> is the same label used for the MD filename in Step 3 (2026-W17 or 2026-04-25_to_2026-04-26).
After the write succeeds, print exactly one line to chat:
HTML report: /tmp/nv-analytics-<label>-<suffix>.html
If the write fails, surface the error to the user verbatim. The MD note has already been written — the failure is non-fatal for the overall skill.
If buckets.total.sessionsTotal === 0, still write the HTML. The html-prompt.md empty-period rules cover the layout.
If buckets.total.sessionsTotal === 0, still write the note. TL;DR: "Sessions touching the vault: 0. No patterns observed." This is a valid and intentional result.
prompt.md so iterating on it does not require rebuilding the CLI.Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub alexmost/neuro-vault-analytics --plugin neuro-vault-analytics