Skip to main content
PythonSteveGJones

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.

Stars
38
Source
SteveGJones/ai-first-sdlc-practices
Updated
2026-05-11
Slug
SteveGJones--ai-first-sdlc-practices--kb-stats
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/SteveGJones/ai-first-sdlc-practices/HEAD/plugins/sdlc-knowledge-base/skills/kb-stats/SKILL.md -o .claude/skills/kb-stats.md

Drops the SKILL.md into .claude/skills/kb-stats.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

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

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