# Kb Stats

> Pure-Python knowledge base statistics dashboard. Reads shelf-index and log.md; emits Inventory, Layer distribution, Domain distribution, Recent Activity, and Staleness sections. No agent dispatch. Read-only. Use when this capability is needed.

- Skill: `tomevault-io/kb-stats` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/kb-stats`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/kb-stats/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/kb-stats

---


# Knowledge Base Statistics

> **Lightweight**: This skill reads only index metadata (shelf-index + log.md). Inline execution is acceptable — no agent dispatch needed.

Surfaces library health metrics in a single markdown report.

## Arguments

- `--output <path>` — Write report to a file instead of stdout
- `--since <ISO-date>` — Override the recent-activity window start date (default: 30 days ago)

## Preflight

Read CLAUDE.md `[Knowledge Base]` section to resolve `library_path` (default `library/`) and `shelf_index_path` (default `library/_shelf-index.md`).

## Steps

### 1. Resolve configuration

Extract `library_path`, `shelf_index_path`, and `log_path` (default `library/log.md`) from CLAUDE.md.

### 2. Run kb_stats.py

```bash
python3 -c "
import sys, os, importlib.util
PLUGIN_ROOT = os.environ.get('CLAUDE_PLUGIN_ROOT', '')
SCRIPTS = os.path.join(PLUGIN_ROOT, 'scripts')
INIT = os.path.join(SCRIPTS, '__init__.py')
if os.path.isfile(INIT) and 'sdlc_knowledge_base_scripts' not in sys.modules:
    spec = importlib.util.spec_from_file_location(
        'sdlc_knowledge_base_scripts', INIT,
        submodule_search_locations=[SCRIPTS])
    if spec and spec.loader:
        mod = importlib.util.module_from_spec(spec)
        sys.modules['sdlc_knowledge_base_scripts'] = mod
        spec.loader.exec_module(mod)
from sdlc_knowledge_base_scripts.kb_stats import main
args = ['--library-path', '<library_path>',
        '--shelf-index-path', '<shelf_index_path>',
        '--log-path', '<log_path>']
# If --output <path> passed: args += ['--output', '<output_path>']
# If --since <date> passed:  args += ['--since', '<since_date>']
sys.exit(main(args))
"
```

### 3. Report results

Print the markdown report (5 sections). If `--output` was passed, confirm the file was written.

## What this skill does NOT do

- Does not validate citations (`kb-validate-citations` does that)
- Does not detect contradictions (`kb-lint` does that)
- Does not query findings (`kb-query` does that)
- Does not invoke any agent

## Errors

- **Library directory not found** — run `/sdlc-knowledge-base:kb-init` first
- **No shelf-index** — run `/sdlc-knowledge-base:kb-rebuild-indexes` first

---
> Source: [SteveGJones/ai-first-sdlc-practices](https://github.com/SteveGJones/ai-first-sdlc-practices) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->