instinct-review
starsforks
How to install instinct-review?
softspark/ai-toolkit/instinct-review
$npx -y skills add softspark/ai-toolkit --skill instinct-reviewReviews/promotes/removes instincts from .claude/instincts/*.md. Triggers: instinct review, curate instincts, manage instincts, promote instinct.
SKILL.md
| 1 | # /instinct-review - Manage Learned Instincts |
| 2 | |
| 3 | $ARGUMENTS |
| 4 | |
| 5 | ## What This Does |
| 6 | |
| 7 | Manages the instinct system: project-local behavioral notes that Claude loads at the start of a session. |
| 8 | |
| 9 | Instincts are markdown files in `.claude/instincts/`, loaded at session start by `session-start.sh` whenever any exist (set `AI_TOOLKIT_HOOK_QUIET=1` to suppress). |
| 10 | |
| 11 | ## Commands |
| 12 | |
| 13 | ### List all instincts |
| 14 | ``` |
| 15 | /instinct-review --list |
| 16 | ``` |
| 17 | Shows all instincts with confidence scores and source sessions. |
| 18 | |
| 19 | ### Review and curate |
| 20 | ``` |
| 21 | /instinct-review |
| 22 | ``` |
| 23 | Interactive review: shows each instinct and asks promote/remove/keep. |
| 24 | |
| 25 | ### Promote instinct (always apply) |
| 26 | ``` |
| 27 | /instinct-review --promote <filename> |
| 28 | ``` |
| 29 | |
| 30 | ### Remove instinct |
| 31 | ``` |
| 32 | /instinct-review --remove <filename> |
| 33 | ``` |
| 34 | |
| 35 | ### Clear all instincts |
| 36 | ``` |
| 37 | /instinct-review --clear |
| 38 | ``` |
| 39 | |
| 40 | ## How Instincts Work |
| 41 | |
| 42 | 1. **Authoring**: Instinct files are written by hand — one markdown file per pattern in `.claude/instincts/`. There is no automatic session-end extractor today (see [When NOT to Use](#when-not-to-use)). |
| 43 | 2. **Storage**: `.claude/instincts/<pattern-name>.md`, each carrying a confidence score (see format below). |
| 44 | 3. **Loading**: At session start, `session-start.sh` loads every instinct file into context whenever any exist. No instincts on disk means nothing is loaded; set `AI_TOOLKIT_HOOK_QUIET=1` to suppress. |
| 45 | 4. **Curation**: Use `/instinct-review` to list, promote, remove, or clear them. |
| 46 | |
| 47 | ## Instinct Format |
| 48 | |
| 49 | ```markdown |
| 50 | # Pattern: [pattern name] |
| 51 | Confidence: 0.85 |
| 52 | Sessions: 3 |
| 53 | Last seen: 2026-03-25 |
| 54 | |
| 55 | [Description of the pattern or preference] |
| 56 | ``` |
| 57 | |
| 58 | ## Steps |
| 59 | |
| 60 | 1. Run `ls .claude/instincts/ 2>/dev/null || echo "No instincts yet"` |
| 61 | 2. For each instinct file, read it and display confidence/summary |
| 62 | 3. Based on `$ARGUMENTS`: |
| 63 | - `--list`: display table of all instincts |
| 64 | - `--promote <id>`: set confidence to 1.0, add "pinned" tag |
| 65 | - `--remove <id>`: delete the file |
| 66 | - `--clear`: delete all files in `.claude/instincts/` |
| 67 | - no args: interactive review of each instinct |
| 68 | 4. Report summary of changes made |
| 69 | |
| 70 | ## Rules |
| 71 | |
| 72 | - **MUST** list instincts with their source (session ID or date) so the user can judge provenance — anonymous instincts cannot be curated |
| 73 | - **MUST** confirm before `--clear` — this action is irreversible without a backup |
| 74 | - **NEVER** invent or edit instinct content — this skill curates existing files, it does not generate new ones |
| 75 | - **NEVER** promote an instinct with confidence < 0.7 without explicit user approval — low-confidence patterns are often one-off noise |
| 76 | - **CRITICAL**: the user owns the instinct list. Propose changes in interactive mode; apply silently only for explicit `--promote`, `--remove`, `--clear` flags. |
| 77 | - **MANDATORY**: after any destructive operation, print the deleted or modified filenames so the user has an audit trail |
| 78 | |
| 79 | ## Gotchas |
| 80 | |
| 81 | - Instincts live in **project-local** `.claude/instincts/`, not in `~/.softspark/ai-toolkit/`. Running this skill in a different project sees a different set — do not treat the list as global state. |
| 82 | - Every instinct file loads into session context by default (whenever the directory is non-empty), so each one costs startup tokens. This is why curation matters — prune aggressively and keep the set small. |
| 83 | - Promoted instincts (confidence = 1.0) load into every session's context, costing tokens. Too many pinned instincts bloat startup. Keep ≤10 pinned. |
| 84 | - Instinct files are plain markdown following the format above. If you accumulate many, a `--clear` and re-author is often cleaner than migrating stale notes after a major toolkit bump. |
| 85 | - The filename (`<pattern-name>.md`) is the identity used by `--promote` and `--remove`. Renaming files manually breaks those flags until the user reopens the review UI. |
| 86 | |
| 87 | ## When NOT to Use |
| 88 | |
| 89 | - To **auto-extract** instincts from a session — not implemented. No Stop hook writes instinct files; author them by hand (or via a future extraction tool). This skill curates existing files, it does not generate them. |
| 90 | - To search past session memory — use `/mem-search` |
| 91 | - To edit global toolkit memory files — those live in `~/.claude/projects/*/memory/` and are managed by the auto-memory system, not this skill |
| 92 | - To stop instincts from loading — delete the files with `--clear`, or set `AI_TOOLKIT_HOOK_QUIET=1` to suppress all session-start output. There is no extraction process to disable. |
People who liked this also viewed
6 picksType
- find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 2026
- grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026
- vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026
- improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026
- setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026
- triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026
