activeloopai / activeloopai/hivemind

Onboarding: nudge users to create skills, surface session count

Open
#167 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
1.6k
Forks
107
Avg merge
17h 30m
Merged PRs (30d)
6

Description

## Problem

New (and even longtime) users frequently don't realize that the plugin mines their sessions into reusable skills, or what it takes for a skill to actually get created. Today the only signals are:

- A line in the SessionStart banner mentioning the memory mount.
- Skills silently appearing on disk under `.claude/skills/` when the LLM gate keeps one.
- Nothing in the UI tells the user how many sessions have already been captured, how close they are to the next mining trigger, or what kind of content actually produces a skill.

Concretely, in real sessions today users ask things like *"why aren't skills generated?"* / *"how many messages do I have to write?"* — the answer requires reading `~/.claude/hooks/skillify.log` and `~/.deeplake/state/skillify/.json`, which is not a great onboarding story.

## Goal

Make skill-generation legible from inside a normal session:

1. **Surface session count** in the SessionStart banner.
- Total captured sessions for the user (org-wide).
- Sessions captured in the current project (cwd / git-remote keyed).
- Last session date (or "no sessions yet" on first run).
2. **Surface skill progress** in the same banner.
- Number of skills generated so far for this project.
- Current value of the per-project Stop counter vs. `TRIGGER_THRESHOLD` (default 20).
- Last skillify verdict if any (KEEP / SKIP + 1-line reason), so the user understands the gate is content-driven, not count-driven.
3. **Onboarding nudge** when state shows zero skills generated for this project after N sessions:
- One-line hint pointing at what kinds of sessions actually produce skills (recurring engineering patterns, non-obvious workarounds across 3+ exchanges) — not generic Q&A.
- Link to a one-pager explaining the trigger model (counter + SessionEnd, current-session excluded, LLM gate decides KEEP/SKIP).
4. **First-run experience**: when no sessions have ever been captured for this user, replace the regular banner with a short "what this plugin does + how to get a skill out of it" block.

## Data sources (already present, no new schema needed)

- `~/.deeplake/state/skillify/.json` — `counter`, `skillsGenerated`, `lastDate`, `updatedAt`.
- `sessions` table — count by user / project.
- `skills` table — count by project.
- `~/.claude/hooks/skillify.log` — last verdict (last `verdict=…` line).

## Acceptance criteria

- [ ] SessionStart banner shows `Sessions captured: (this project: )` and `Skills generated (this project): ` and `Next mining trigger: /`.
- [ ] When `skillsGenerated.length === 0` and `counter >= 1`, show a one-line nudge that tells the user *why* a skill might not have been kept (gate criteria), not just *that* none exist.
- [ ] First-run path (no rows for this user in `sessions`) shows a dedicated welcome block instead of the standard banner.
- [ ] All English (per repo policy). No emoji unless we already use it elsewhere in the banner.
- [ ] Numbers fetched in a single SQL round-trip from SessionStart — must not slow session bootstrap noticeably.
- [ ] Unit test in `claude-code/tests/` that mocks the API client and asserts the banner text shape for: (a) brand-new user, (b) user with sessions but zero skills, (c) user with sessions and ≥1 skill, (d) counter at threshold-1.

## Non-goals

- Changing how the LLM gate decides KEEP vs. SKIP — that's content-driven and stays as-is.
- Forcing a skill to be generated on demand. The nudge informs; it does not bypass the gate.
- Per-agent UX changes outside Claude Code in v1. Codex / cursor / hermes / pi banners can follow once the Claude Code version lands.

## Open questions

- Should the banner be silent when state is "boring" (e.g. existing user, ≥1 skill, counter mid-range)? Tentatively yes — minimize noise for steady-state users; show counts only on first-run, on zero-skills, or when counter crosses 50%/100% of threshold.
- Where should the "what produces a skill" one-pager live — `README.md`, a new `docs/skills.md`, or inline in `CLAUDE.md`?

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.