kb-monitor（知识库监视器）

/kb-monitor — KB Usage Monitoring & Skill Gardening

1. Routing

Parse $0 (the first argument) to determine the mode:

• If $0 is --status or empty (default/proactive activation): Follow Section 3 (Status Mode).
• If $0 is --convert: Follow Section 4 (Convert Mode). $1 is the topic path.
• If $0 is --health: Follow Section 5 (Health Mode). $1 is the skill name.
• Otherwise: Show usage: Usage: /kb-monitor [mode] Modes: --status Show candidates + health (default) --convert <topic-path> Convert KB topic to skill --health <skill-name> Check skill health + correction history Examples: /kb-monitor /kb-monitor --convert claude/mcp/ /kb-monitor --health writing-article

1a. Target Format Awareness

When recommending or executing conversions, consider the target environment:

Detect environment from context: if the project has a .claude-plugin/plugin.json, it's a plugin project. If skills reference Cowork connectors or the project targets Cowork, recommend the Cowork path.

For plugin projects, also track plugin candidates — groups of related skills that could be bundled under a shared namespace. A group becomes a plugin candidate when 3+ skills share a common category prefix.

2. References

2a. Data Sources

Access Log

Run analyze_access.py to query the access log without loading it into context:

uv run ${CLAUDE_SKILL_DIR}/scripts/analyze_access.py --top-topics --candidates --health --format=json

Output is compact JSON (~50-100 tokens).

Global KB Suggestions

Check for pending suggestions to global (read-only) KBs:

uv run ${CLAUDE_SKILL_DIR}/../kb-learn/scripts/suggestion.py list --status pending --json

If count > 0, include in status output. Alert when > 5 pending suggestions.

Memory

Read the memory file at the standard Claude memory location for this project. Look for monitoring_kb_observations.md. This contains:

• Skill candidate tracking (KB topics, session counts, status)
• Skill health tracking (corrections, status)
• Conversion history
• Policy gates (exclude, cooldown, condition, throttle)

2a. Agents

Use the analyzer agent when the access log is large (1000+ entries). For most cases, the analyze_access.py CLI output is sufficient.

3. Status Mode (--status)

1. Gather data: Run analyze_access.py --top-topics --candidates --health --format=json
2. Check suggestions: Run suggestion.py list --status pending --json to count pending global KB suggestions
3. Read memory: Load monitoring_kb_observations.md from memory directory
4. Present findings: Skill Candidates: For each candidate topic (high read count, no skill/ folder): Skill Health Issues: For each skill with corrections in memory: Pending Suggestions (Global KBs): If any pending suggestions exist, show count and summary per target KB. Alert if > 5 pending — user should review in the global KB repo. Recent Conversions: List from memory's Conversion History table.

- Topic name, session count, total reads - Whether memory has any gate (cooldown, exclude, condition) - Recommendation: "Convert?", "Skip", "Never for this topic" - Skill name, correction count, last issue description - Status: watch (1-2 corrections), action (3+ corrections) - Recommendation: "Fix?", "Skip", "Mark resolved"

1. Prompt for action: Use AskUserQuestion to ask the user what to do with each candidate/issue. Present the options clearly (Convert / Fix / Skip / Never / Not now / Wait until condition). Then process:

- "Convert" → Switch to Section 4 (Convert Mode) for that topic - "Fix" → Switch to Section 5 (Health Mode) for that skill - "Skip" → No action, no memory update - "Never" → Add exclude gate to memory's Policy Gates table - "Not now" → Add cooldown gate with session count to memory - "Wait until <condition>" → Add condition gate to memory

1. Update memory: After each interaction, update monitoring_kb_observations.md:

- Update candidate session counts and statuses - Record any new policy gates - Keep under 100 lines (archive old entries)

4. Convert Mode (--convert <topic-path>)

Delegate the actual conversion to /kb-mint:

/kb-mint --skill <topic-path>

After kb-mint completes the conversion:

1. Update monitoring memory: Add conversion record to memory's Conversion History table
2. Remove from candidates: Remove the topic from Skill Candidates table
3. If plugin project: Suggest follow-up: /kb-mint --plugin <new-skill-name> (in plugin contexts, use the namespaced form instead)

5. Health Mode (--health <skill-name>)

1. Read memory: Load correction history for this skill from monitoring_kb_observations.md
2. Read skill files: Load the skill's SKILL.md and key reference files
3. Present health summary:

- Correction count (30-day window) - Specific issues from memory's Skill Health table - Comparison between recorded issues and current skill content

1. Offer remediation: Use AskUserQuestion to ask the user which action to take:

- "Fix" → Run /kb-learn fix with pre-filled description constructed from correction history - "Mark resolved" — if issues have been fixed - "Skip" — no action

1. Update memory: Record health check, update status

6. Memory Management

Memory File Location

Standard Claude memory: ~/.claude/projects/<project-key>/memory/monitoring_kb_observations.md

Memory File Structure

---
name: kb-monitoring-observations
description: Cross-session KB access patterns, skill health scores, conversion history, and pending recommendations
type: project
---

# KB Monitoring Observations

## Skill Candidates
| KB Topic | First Seen | Sessions | Status |
|----------|-----------|----------|--------|

## Skill Health
| Skill | Corrections (30d) | Last Issue | Status |
|-------|-------------------|------------|--------|

## Conversion History
| Topic | Converted | Skill Name |
|-------|-----------|------------|

## Policy Gates
| Topic/Skill | Gate Type | Condition | Set On |
|-------------|-----------|-----------|--------|
| * (global) | throttle | max 1 conversion suggestion per session | — |

Gate Types

• exclude: Never surface this topic/skill (permanent)
• cooldown: Wait N more sessions before resurfacing
• condition: Don't surface until free-text condition is met
• throttle: Global rate limits on recommendation frequency

Housekeeping

• Keep memory file under 100 lines
• Archive old conversion history entries (older than 90 days)
• Remove stale cooldowns when session count is met
• Remove conditions when user confirms they're resolved