| name | inc-os:improve-system |
| description | Improve your system. Improves skills from iteration, captures experiences, reviews session history for knowledge, audits for rot, and sets up foundation content. Routes automatically based on context. |
/inc-os:improve-system
Make your entire system smarter based on what just happened. One skill, five modes. The model determines which mode based on conversation context, or you can specify.
Resolve the knowledge layout
Check the repo layout before any path work:
- If
knowledge/wiki/ exists → knowledge layout: WIKI = knowledge/wiki/, RAW = knowledge/raw/.
- Otherwise → flat layout:
WIKI = wiki/. There is no raw layer.
clients/ exists only in some repos. Run client-routing steps only when the clients/ folder exists; otherwise skip them and route everything through WIKI.
Every WIKI/... path below means the resolved folder (e.g. knowledge/wiki/offers/ in knowledge layout, wiki/offers/ in flat layout).
Arguments
The invocation may include an argument that names the mode directly. If present, skip Step 0 and jump straight to that mode:
| Argument | Mode |
|---|
skill (optionally skill <skill-name>) | Skill Improvement, targeting the named skill if given |
experience | Experience Capture |
sessions | Session Review |
audit | System Audit |
foundation (optionally foundation <area>) | Foundation — if an area is named (brand-voice, offers, audience, tools), run only that interview |
Examples: /inc-os:improve-system foundation, /inc-os:improve-system foundation tools, /inc-os:improve-system skill save-system.
Anything else passed as an argument is treated as free-text context for Step 0 mode detection.
Modes
| Mode | Trigger | What it does |
|---|
| Skill | You iterated on a skill's output | Updates the skill's process, learnings, or steps |
| Experience | You have a story, win, or lesson to capture | Writes a structured experience entry |
| Session Review | You want to extract value from recent Claude Code sessions | Reads history, pulls out transferable learnings |
| Audit | You want to check the system for rot | Finds stale, conflicting, duplicate, or orphaned content |
| Foundation | The project is missing foundational content (brand, offers, audience, tools) | Auto-discovers foundation sub-skills and runs interviews to fill gaps |
Instructions
Step 0: Determine Mode
Look at the conversation context and determine which mode(s) apply:
Skill mode if:
- A skill or slash command was used in this conversation
- There were 3+ rounds of feedback/revision on the output
- The user corrected the skill's behavior ("no, do it this way")
- The user says "improve this skill" or "based on our back and forth"
Experience mode if:
- The user mentions something that happened to them (client work, a win, a mistake, a lesson)
- The user pastes a voice transcript or describes their day
- The user says "log this" or "capture this"
Session Review mode if:
- The user says "review my sessions" or "what did I work on"
- The user wants to extract learnings from past work they didn't capture in the moment
- It's been a while since the last review
Audit mode if:
- The user says "audit" or "check for rot" or "clean up"
- The user suspects something is outdated or conflicting
- It's been 2+ weeks since the last audit
Foundation mode if:
- The user says "set up foundation", "what's missing", "set up brand/offers/audience", or similar
- This is a new project or new onboarding session and the wiki is largely empty
- Bare invocation in a project where any of
WIKI/brand-voice/, WIKI/offers/, WIKI/audience/, WIKI/tools/ are empty or missing
If unclear, ask with the AskUserQuestion tool ("What are we improving?"). Offer the 3-4 most plausible modes given conversation context as options, each with a one-line description:
- Improve a skill — based on our back-and-forth
- Capture an experience — story, win, lesson
- Review recent sessions — extract missed learnings
- Audit the system — find stale or conflicting content
- Set up foundation — brand, offers, audience, tools
The user can always describe something else via the built-in "Other" option.
Multiple modes can run in one invocation if relevant.
Mode 1: Skill Improvement
Step 1: Identify the skill
From conversation context, determine which skill was used. If ambiguous, ask.
If user says "based on our conversation" without naming a skill, infer from context which skill(s) are relevant.
Step 2: Extract learnings
Review the conversation for:
- Corrections ("no, not like that") that reveal missing rules or steps
- Confirmed approaches that worked (non-obvious choices the user approved without pushback)
- Process friction (steps that were skipped, reordered, or didn't apply)
- New questions the skill should ask upfront
- Feedback interpretation (e.g., "tighter" means cut filler, not rewrite sections)
Step 3: Read the skill and understand its structure
Read the skill's SKILL.md (or equivalent). Identify:
- Current steps and process
- Which wiki folders or files it loads
- Existing learnings (count them, check for conflicts)
- Whether learnings live in SKILL.md or in a separate file it references
Step 4: Find neighboring skills
Neighboring skills are skills that load the same wiki folders. When you improve one, the learning might apply to others.
How to find neighbors:
- Read the target skill's context/load instructions
- Find which knowledge paths it references
- Search other skill files for the same path references
- Also check agents that reference the same knowledge
Show neighbors only if the learning applies to them. Don't ask about empty matches.
Step 5: Propose changes
Show:
"Here's what I'd update in [skill-name]:
Current state: [X steps, Y learnings, loads Z folders]
Proposed changes:
- [specific change to process, learning, or step]
- [specific change]
Neighboring skills that might need the same update:
- [skill-name]: [why this learning applies]"
Then ask with the AskUserQuestion tool: Apply all / Apply without neighbors / Adjust first.
Step 6: Check for contextual rot within the skill
After proposing changes, scan the skill for:
- Duplicate learnings: Same advice stated differently in multiple places
- Conflicting learnings: "Always do X" vs "Never do X" in the same skill
- Learning bloat: 30+ learnings in one section (suggest grouping, promoting stable ones to process, or archiving obvious ones)
- Stale references: Tool names, file paths, or examples that no longer exist
If found, flag them alongside the proposed changes.
Step 7: Apply on approval
Update the skill file(s) and any approved neighbors. Confirm what changed.
Mode 2: Experience Capture
Step 1: Get the experience
Either from:
- Conversation context (the user described something)
- A pasted voice transcript
- A typed description
- Claude Code session history (what was actually built)
Step 2: Extract structured content
From the raw input, extract:
- Key stories: What happened, the challenge, what was tried, what worked, the outcome. Write in first person, past tense, conversational.
- Quotable moments: Punchy phrases that sound natural and could go into content verbatim
- Insights: Transferable lessons that apply beyond this specific situation
- Tags: Topics covered (e.g., data-loops, client-work, delegation, tool-setup, pricing, mistakes, wins, frameworks)
Step 3: Find where to write
Scan the project for an experience directory:
- Check for
WIKI/experiences/, docs/experiences/, or similar paths
- Check CLAUDE.md for documented paths
- If nothing exists, ask where to create it.
Step 4: Write the entry
Write as {path}/{YYYY-MM-DD}-{brief-slug}.md:
# {YYYY-MM-DD} - {Brief Descriptive Title}
## Metadata
- **Date**: YYYY-MM-DD
- **Topics**: [topic1, topic2, topic3]
- **Source**: [voice-transcript | session-history | combined | typed]
## Key Stories
### Story 1: {Story Title}
{Narrative: specific context, the challenge, what you tried, what worked, the outcome}
## Quotable Moments
> "{Direct quote that sounds natural and punchy}"
## Insights & Learnings
- {Transferable insight}
- {Another learning}
## Tags
{topic1, topic2, topic3}
Step 5: Cross-reference
Check if this experience is relevant to any active projects in the workspace. If so, mention which project and where the story might fit.
Step 6: Ingest into wiki
After writing all experience entries, automatically run the /inc-os:add-new-resource process on each file:
- Add a
## Summary section with source type, key entities, key concepts, and ingestion date
- Extract entities and concepts worth tracking in the wiki
- Create or update wiki pages for substantive new concepts
- Add
[[wikilinks]] to the source file for first mentions of wiki entities
- Update
WIKI/_Home.md if any new top-level wiki sections were added
For multiple entries, batch the wiki updates at the end (one pass, not per-file). Use parallel agents when processing 3+ files to speed this up.
Mode 3: Session Review
Step 1: Read session history
Read ~/.claude/history.jsonl (last 500 lines or configurable). Extract:
- Projects worked on: Group by
project field, using the display field for prompt text
- Skills/commands used: Prompts starting with
/
- Timeline: Use
timestamp to order the day's/week's work
- Patterns: creation, debugging, iteration, discovery
- Pasted content: Check
pastedContents field for error messages, transcripts, or meeting notes included in prompts
Also supplement with git log --oneline --since="2 weeks ago" to see what was actually committed, which is often richer than the history file alone.
Step 2: Identify extractable learnings
Look for:
- Skill iteration: Sessions where a skill was invoked and then had multiple rounds of feedback (potential skill improvements)
- Repeated patterns: Things becoming habits across sessions (e.g., same skill cloned to multiple projects)
- Problems solved: Debugging sessions that could inform future work
- Tools/approaches discovered: New tools, APIs, or workflows figured out
- Implicit learnings: Repeated debugging of the same thing suggests a "gotcha" worth documenting
- Cross-project patterns: The same action taken in multiple projects signals a universal principle
- System evolution: Changes to how the system itself works (new skills, new onboarding flows, new interfaces)
Step 3: Present draft entries and interview
Present 2-5 draft entry summaries (title + 2-3 sentence description each). Do NOT write the full entries yet.
Then interview the user to dig deeper. For each entry, ask 2-3 targeted questions:
- "Why now?" - What triggered this specific action? Was it reactive (something broke) or proactive (building ahead)?
- "Who benefits?" - Is this just for you, or does it affect teammates, clients, or a future audience?
- "What's the bigger pattern?" - Does this connect to a broader shift in how you work? Is this a one-off or the start of something?
- "What was the alternative?" - What would you have done without this? What was the old way?
- "What surprised you?" - Anything unexpected in how it played out?
Pick the most relevant questions per entry. Don't ask all of them for every entry. The goal is to surface the insight behind the action, not just document what happened.
Continue the interview for 1-2 rounds until the entries feel rich enough to capture something transferable, not just a log of what was built.
Step 4: Generate full entries
After the interview, write entries using the Experience mode format (Step 2-4 from Mode 2). Each entry should include:
- Key stories enriched with interview context
- Quotable moments (pull directly from interview responses when possible)
- Insights that are transferable beyond the specific session
Generate entries for significant sessions only (2-5 entries). Skip trivial sessions.
Step 5: Write entries
Same path detection as Experience mode. Write each entry as a separate file.
Step 6: Suggest skill improvements
If the session review reveals skill iteration patterns (a skill was used with multiple rounds of feedback), offer to switch to Skill mode for those specific skills.
Mode 4: System Audit
Step 1: Map the system
Scan for all components:
- All skill files (
.claude/skills/, .claude/commands/)
- All wiki files (
WIKI) and docs (docs/). Client material (clients/, when the folder exists) is in scope for orphan/link checks but never for cross-project lifting.
- All agent files (
.claude/agents/)
- CLAUDE.md and any
.claude/rules/ files
Build two maps:
Dependency map (what uses what):
skill-name -> reads: WIKI/path/a/, WIKI/path/b/
agent-name -> reads: WIKI/path/c/
Link graph (for projects using wikilinks/Obsidian):
For each .md file, extract outgoing [[wikilinks]] and markdown links to local files. Build incoming/outgoing link maps.
Step 2: Run checks
Check 1: Broken links (high severity)
- Wikilinks or file references that point to files that don't exist
- Check case-insensitive and partial path matches before flagging
Check 2: Conflicting rules (high severity)
- Two files giving opposite guidance on the same topic
- Skill learnings that contradict each other ("always do X" vs "never do X")
- Different sources recommending opposite approaches without documenting when each applies
Check 3: Orphaned content (medium severity)
- Knowledge files that no skill or agent references
- Files with zero incoming AND zero outgoing links (graph orphans)
- Exclude structural files (INDEX.md, README.md, etc.)
Check 4: Missing pages (medium severity)
- Wikilink targets that appear in 2+ source files but have no actual page
- Concepts referenced repeatedly but never defined
Check 5: Stale content (low severity)
- Files not updated in 120+ days (use
git log -1 --format="%ai" -- [file])
- Skip inherently stable files (voice patterns, brand briefs, frameworks)
Check 6: Coverage gaps (low severity)
- Topics that appear in 3+ projects/experiences but have no knowledge entry
- Scan project folders and experience files for recurring themes
Check 7: Duplicate content (low severity)
- Multiple files covering the same ground without cross-linking
- Similar filenames in the same domain (e.g.,
brand-context.md and brand-brief.md)
Check 8: Learning bloat (low severity)
- Skills with 30+ learnings in one section
- Suggest: group related learnings, promote stable ones to process, archive obvious ones
Step 3: Report findings
Show a summary first:
SYSTEM AUDIT
============
Components: X skills, Y agents, Z wiki files
Referenced: X files used by skills/agents
Orphaned: X files
Broken links: X
Conflicts: X
Stale: X
Gaps: X
HEALTH SCORE: X/10
Then show each category with details, grouped by severity.
Step 4: Fix on approval
- Broken links: Find closest matching file, fix the link or offer to create a stub
- Conflicts: Propose a resolution that documents when each approach applies
- Orphans: Ask if should be deleted, connected to a skill, or kept as reference
- Stale files: Read the file, check if content is still accurate, propose updates
- Gaps: Propose a new knowledge file with a starter outline
- Duplicates: Read both files, propose consolidation or cross-linking
- Bloat: Propose grouping, promotion to process, or archiving
Never auto-delete without explicit approval.
Step 5: Rebuild index (if project uses one)
If the project has a wiki home file (e.g., WIKI/_Home.md), rebuild its section index with:
- Files by domain
- Cross-references (topics covered by multiple sources)
- Dependency map (skill -> wiki paths, wiki paths -> skill)
- Unlinked wiki pages
Mode 5: Foundation
Every Incubator OS project has the same four foundation areas: brand voice, offers, audience, and tools. The first three produce the source-of-truth wiki content every downstream draft reads from; tools captures the systems the business runs on so skills and automations know what exists. Foundation mode detects which areas are empty and runs the right interview to fill them.
The interview content lives in this plugin (not in the project). The wiki content lives in the project at WIKI/brand-voice/, WIKI/offers/, WIKI/audience/, WIKI/tools/.
The four foundation areas
| Area | Wiki path | Interview file |
|---|
| Brand voice | WIKI/brand-voice/ | $CLAUDE_PLUGIN_ROOT/skills/improve-system/foundation/brand-voice.md |
| Offers | WIKI/offers/ | $CLAUDE_PLUGIN_ROOT/skills/improve-system/foundation/offers.md |
| Audience | WIKI/audience/ | $CLAUDE_PLUGIN_ROOT/skills/improve-system/foundation/audience.md |
| Tools | WIKI/tools/ | $CLAUDE_PLUGIN_ROOT/skills/improve-system/foundation/tools.md |
All four share interview principles defined in $CLAUDE_PLUGIN_ROOT/skills/improve-system/foundation/principles.md. Read once before running any interview.
Step 1: Check status of each area
For each of the four wiki paths, check completion:
- populated — path exists and contains at least one file other than
.gitkeep
- empty — path exists but has only
.gitkeep (or nothing)
- missing — path does not exist
Use ls or equivalent. Treat the project root as the current working directory.
Step 2: Report status
FOUNDATION STATUS
=================
+ brand-voice WIKI/brand-voice/ (populated)
x offers WIKI/offers/ (empty)
x audience WIKI/audience/ (empty)
x tools WIKI/tools/ (missing)
If all four are populated, say so and stop.
Step 3: Prompt and dispatch
If any area is empty or missing, ask with the AskUserQuestion tool (multiSelect, one option per empty area, plus context like "Which foundation interviews should we run now? Each takes 10-20 minutes."). Each option gets a one-line description of what the interview produces.
If the invocation argument already named an area (e.g., foundation tools), skip the question and run that interview directly.
For each chosen area:
- Read
$CLAUDE_PLUGIN_ROOT/skills/improve-system/foundation/principles.md once at the start of the session (re-use for subsequent areas in the same run).
- Read the corresponding interview file (e.g.,
$CLAUDE_PLUGIN_ROOT/skills/improve-system/foundation/brand-voice.md).
- Run the interview as described in that file. Write outputs into the corresponding wiki path.
Create the wiki directory if it does not exist. Remove the .gitkeep file once real content lands.
Step 4: Verify
After each interview, confirm the wiki path now contains the expected files. If not, note what's still missing.
Step 5: Suggest related work
Once foundation is complete, mention that:
/inc-os:save-system automatically treats WIKI/brand-voice/, WIKI/offers/, and WIKI/audience/ as sensitive on every push (WIKI/tools/ is not flagged; it holds tool names and roles, never credentials).- Project-specific skills can read these files directly to load brand / offer / audience / tool context into their prompts.
Rules
- Don't force learnings from single instances. Only promote a pattern to a skill when it recurs 3+ times.
- Don't auto-run without approval. Always show what you'll change and ask first.
- Respect the existing structure. Write to the directories the project already uses. Don't create new structures when one exists.
- Be honest about what you find. If the system is clean, say so. Don't invent problems.
- Multiple modes in one run is fine. If you improved a skill and found an experience worth capturing, do both.
- Keep entries useful, not comprehensive. A good learning is transferable to future work, not just a diary entry.
- Contradictions aren't always bad. Sometimes two sources genuinely disagree. The resolution is documenting when to use which approach, not picking a winner.
- Confirmed approaches matter as much as corrections. Don't only save mistakes. If a non-obvious approach worked and was approved, that's a learning too.
