Help us improve
Share bugs, ideas, or general feedback.
From mycelium
ALWAYS use this skill when the user mentions "mycelium", "living repo", "crystallize", or "todo idea". ALWAYS use for requests about making projects self-documenting, tracking knowledge/decisions/learnings, capturing insights for later, transferring knowledge across projects, or exploring unfamiliar data. This skill manages a .living/ directory framework that registers analyses, datasets, and decisions. It handles: project initialization ("set up mycelium", "initialize living repo"), knowledge capture ("crystallize this learning", "record this finding"), future work tracking ("add a todo idea", "track this for later"), knowledge transfer ("transfer knowledge", "cross-pollinate", "sync learnings"), dataset ingestion, convention installation, and progressive disclosure knowledge systems. NOT for: report writing, code refactoring, brainstorming, git init, or generic folder organization.
npx claudepluginhub arjunrajlaboratory/mycelium --plugin myceliumHow this command is triggered — by the user, by Claude, or both
Slash command
/mycelium:coreThe summary Claude sees in its command listing — used to decide when to auto-load this command
# Mycelium — Living Repository Skill (Core) When invoked, determine which mode the user needs based on their request, then follow the corresponding protocol. For analysis, report generation, idea brainstorming, and code review, direct the user to the dedicated skills: - `/mycelium:analyze` — start or continue an analysis - `/mycelium:report` — generate a structured report - `/mycelium:ideas` — brainstorm with disciplinary personas - `/mycelium:transfer` — cross-pollinate learnings across sibling projects - `/mycelium:review` — review code/analysis changes (PR, commit, or diff) for the kin...
Share bugs, ideas, or general feedback.
When invoked, determine which mode the user needs based on their request, then follow the corresponding protocol.
For analysis, report generation, idea brainstorming, and code review, direct the user to the dedicated skills:
/mycelium:analyze — start or continue an analysis/mycelium:report — generate a structured report/mycelium:ideas — brainstorm with disciplinary personas/mycelium:transfer — cross-pollinate learnings across sibling projects/mycelium:review — review code/analysis changes (PR, commit, or diff) for the kinds of mistakes that matter in scientific work; supports grill mode for conversational interrogation of analytical decisionsinitTrigger: "set up mycelium", "initialize living repo", "restructure this repo"
Purpose: Scaffold a new or existing repo into a mycelium-enabled living repository.
Steps:
.living/ directory).skills/core/scripts/init_repo.py.network/conventions/*/CONVENTION_PACK.yaml for packs with core: true and install each one using skills/core/scripts/install_convention.py. Currently the core packs are robust-analysis, report-generator, and idea-generator. These provide batteries-included practices every repo should have.skillpacks/ with .gitignore and README.md. This is where external skill repos (bioSkills, scientific-agent-skills, Autonomous-Science) are cloned for use by the skill-bridge convention. The repos are inert reference libraries — never installed as agent skill packs. Prompt the user to clone the repos:
cd skillpacks/
git clone https://github.com/K-Dense-AI/scientific-agent-skills.git
git clone https://github.com/GPTomics/bioSkills.git
git clone https://github.com/arjunrajlaboratory/Autonomous-Science.git
core: true.CLAUDE.md for the repo (from skills/core/templates/CLAUDE.md.template) that encodes the living repo protocol.ENVIRONMENTS_INSTALLATIONS.md at repo root.ANALYSIS_MANIFEST.md, DATA_MANIFEST.md, ALGORITHM_MANIFEST.md, REFERENCE_MANIFEST.md)..living/ with empty decisions.md, learnings.md, conventions.md; create .living/log/LOG_REGISTRY.md (session log registry — tracks work across sessions). Create .living/outputs/knowledge-transfers/ for cross-project transfer audit trail.~/.claude/knowledge/ does not exist, run skills/core/scripts/init_knowledge.py to set up the global progressive disclosure knowledge system. The script also appends the Global Knowledge Domains routing table to every ~/.claude/projects/*/memory/MEMORY.md (idempotent — skips files where the header is already present). Generate .living/INDEX.md for the newly scaffolded project using skills/core/scripts/generate_index.py --summary-heuristic.todo/ directory with TODO_REGISTRY.md (registry table) and TODO_ITEM_TEMPLATE.md (template for individual items). Copy these from the mycelium todo/ directory.skills/core/scripts/validate_structure.py to confirm everything is correct.References to consult:
skills/core/references/folder-structure.md — canonical target structureskills/core/references/environment-setup.md — environment setup conventionsingestTrigger: "ingest dataset", "add data", "import data"
Purpose: Pull a new dataset into the analytical framework.
Steps:
skills/core/references/data-ingest-conventions.md.data/raw/[dataset-name]/.data/metadata/[dataset-name]/ using templates: skills/core/templates/schema.yaml for column definitions, skills/core/templates/provenance.md for source documentation, and skills/core/templates/summary_stats.md for statistical overview.data/DATA_MANIFEST.md with new entry (use skills/core/templates/dataset-manifest-entry.yaml)..living/decisions.md.install-conventionTrigger: "install convention", "add bioinformatics conventions", "install convention pack"
Purpose: Install a convention pack from the mycelium network into the current repo.
Context: Core packs (robust-analysis, report-generator, idea-generator) are auto-installed during init. This mode is primarily for adding domain packs after initialization, but can also be used to manually install or reinstall any pack.
Steps:
skills/core/references/marketplace-guide.md.network/conventions/, noting which are core (already installed) and which are domain (available to add).skills/core/scripts/install_convention.py to copy conventions into .living/conventions/[name]/..living/conventions/ACTIVE_CONVENTIONS.yaml.CLAUDE.md to reference new convention pack.crystallizeTrigger: "crystallize learnings", "review learnings", "extract patterns"
Purpose: Review accumulated learnings and propose new conventions.
Steps:
skills/core/references/skill-generation-guide.md.skills/core/templates/learning-entry.md for the entry format used in learnings.md (entries start with ### [YYYY-MM-DD] and have Category, Tags, mitigation_type, and structural_mitigation_candidate fields — use Tags for pattern clustering, and mitigation_type for recurrence-risk assessment)..living/learnings.md and .living/decisions.md.skill-generation-guide.md — minimum 3 related entries sharing tags or themes. See the worked example in that guide for the complete input→output transformation. To surface near-duplicate entries automatically, run python3 skills/core/scripts/detect_recurrence.py --living-dir <path> — it flags clusters of ambient-awareness learnings that are strong candidates for convention promotion or structural mitigation.~/.claude/knowledge/{domain}.md using the structured entry template (What/Evidence/When useful/Scope/Status/Last validated). Set status: unreviewed — the weekly audit will confirm..living/generated-conventions/[name]/ using the template at skills/core/templates/generated-convention.md.ORIGIN.md linking back to the learnings that spawned it.crystallize-findingsTrigger: "crystallize findings", "extract findings", "log findings"
Purpose: Extract scientific findings from recent work and organize them into topic-based files.
Steps:
.living/log/ most recent file) and any generated analysis outputs.learnings.md)..living/).
b. Read {meta-project}/.living/findings/INDEX.md if it exists.
c. Semantically match the finding against existing topics.{project}/.living/findings/{topic-slug}.md using the entry template from skills/core/templates/findings-entry.md.{project}/.living/findings/{topic-slug}.md using the topic template from skills/core/templates/findings-topic.md..living/findings/FINDINGS_REGISTRY.md. If the file doesn't exist, create it from skills/core/templates/findings-registry.md. Match on finding ID (F-NNN) — update the existing row if the ID is already present, or append a new row. Columns: ID, Claim, Status, Topic (link to topic file), Implications, Tags, Last Updated.python3 skills/core/scripts/crystallize_findings.py to rebuild the cross-project INDEX.md and regenerate all per-project FINDINGS_REGISTRY.md files from the topic file source of truth.transferTrigger: "transfer knowledge", "cross-pollinate", "sync learnings", "knowledge transfer"
Dormant by design — requires meta-project layout. This mode only fires when the current repo sits inside a parent directory that itself has
.living/(the "meta-project"), or when the current repo is the meta-project with ≥2 sibling projects each having.living/. Sibling repos at the same parent level (e.g.~/code/projA/,~/code/projB/) do NOT qualify. If your repos are siblings, either (a) nest them under a common meta-project directory andinitthe parent, or (b) skip this mode entirely.
Purpose: Cross-pollinate learnings across sibling projects in a meta-project. Identifies insights from one project that would benefit others and automatically applies them to target projects' .living/learnings.md files.
Steps:
commands/transfer.md.sonnet model and do not block on results..living/learnings.md with source: {project} (auto-transferred by mycelium) for auditability.{meta-project}/.living/outputs/knowledge-transfers/YYYY-MM-DD.md.When this runs:
mycelium-health.sh checks .living/outputs/knowledge-transfers/.last-run at session start. If >24h old or missing, it emits a directive to dispatch the transfer as a background subagent./mycelium:transfer or says "transfer knowledge", "cross-pollinate".Lifecycle position: This phase sits between crystallization (patterns → conventions) and contribution (conventions → network). Crystallize extracts patterns within a project; transfer propagates relevant patterns across projects; contribute shares generalized patterns with the network.
Notes:
contributeTrigger: "contribute convention", "share back", "submit to network"
Dormant by design — manual workflow. This mode does not fire automatically. It runs only when a user explicitly asks to contribute a convention back to the network, and requires that
crystallizemode has previously produced a.living/generated-conventions/[name]/to package. Most projects never reach this stage; that is normal.
Purpose: Package a repo-local generated convention for PR to the mycelium network.
Steps:
.living/generated-conventions/[name]/ — if not, run crystallize mode first.ORIGIN.md provenance document./home/user/hospital-x/data/ → [data-source-path], "Hospital X CSV exports" → "external tabular data sources")skills/core/references/skill-generation-guide.md for referenceanalysis-conventions.md directlyanalysis-conventions.md) that links to detail files covering specific aspectsnetwork/conventions/robust-analysis/ for an example of a multi-file packnetwork/community-contributed/[name]/:
CONVENTION_PACK.yaml — use template at skills/core/templates/convention-pack.yamlanalysis-conventions.md — the generalized convention (hub file with progressive disclosure)qc-checklist.md — quality control checklist for applying the convention correctlystatistical-conventions.md)templates/ — reusable templates if applicablefile-issueTrigger: "file issue", "report convention gap", "report bug in convention"
Dormant by design — manual workflow. Fires only when a user explicitly asks to file a network-side issue. No automation routes to this mode.
Purpose: Report a convention gap or error to the mycelium network.
Steps:
convention-gap, convention-improvement, or new-domain-request.recallTrigger: "what do we know about X", "find learnings tagged Y", "fetch entry L-42", "/recall"
Purpose: Targeted lookup of .living/learnings.md and .living/decisions.md entries by tag, ID, or date — without pulling whole files into context.
Steps:
--tag <tag> (repeatable for ANY-match)--id L-42 or --id D-7 (repeatable)--since YYYY-MM-DDpython3 skills/core/scripts/recall_lessons.py --living-dir .living/ [filters].--max 20 by default.learnings.md/decisions.md.Discovery: Tag → ID maps live in .living/INDEX.md under the By tag subsection (regenerated by the SessionStart hook). Use it to find candidate IDs before recall.
migrateTrigger: "migrate this repo", "upgrade mycelium", "this is an old repo"
Purpose: Bring a repo started on an earlier mycelium version up to current spec — adds the .living/INDEX.md knowledge-index callout to CLAUDE.md, tops up missing hooks (e.g. read-tracker), regenerates the heuristic SUMMARY block, and appends the Global Knowledge Domains routing table to MEMORY.md.
Steps:
python3 skills/core/scripts/migrate_existing_repos.py --repo . (or --scan <parent-dir> to migrate every child).--dry-run first to preview changes.todo-ideaTrigger: "todo idea", "add todo", "I have an idea", "track this for later", "/todo-idea"
Purpose: Capture a future work item, idea, or planned improvement in the project's todo/ directory.
Steps:
compare-public-data.md).todo/[filename].md using the template at todo/TODO_ITEM_TEMPLATE.md. Fill in all fields from user input. Set status to open. Set date to today. Set author to the user's name (ask if unknown).todo/TODO_REGISTRY.md with: item title, priority, status, category, date, author, and a link to the file.Notes:
todo/ or todo/TODO_REGISTRY.md doesn't exist yet, create them first (use the structure from the mycelium todo/ directory as reference).knowledge-initTrigger: "knowledge init", "set up knowledge", "initialize knowledge system", "progressive disclosure"
Purpose: Bootstrap the global progressive disclosure knowledge system (~/.claude/knowledge/).
Steps:
skills/core/scripts/init_knowledge.py to create domain files from templates. Existing files are preserved (idempotent)..living/ directory: run skills/core/scripts/generate_index.py to create/update .living/INDEX.md.~/.claude/projects/*/memory/). If missing the "Global Knowledge Domains" table, append it from skills/core/templates/knowledge/domain-table.md.~/.claude/knowledge/.last-audit exists, confirm domain file count, report summary.Notes:
~/.claude/knowledge/ which is shared across all projects.mycelium-health.sh) handles ongoing maintenance: staleness checks, INDEX.md regeneration, skills sync, dedup.References to consult:
skills/core/templates/knowledge/domains.yaml — domain registry (single source of truth for domain definitions)skills/core/templates/knowledge/domain-table.md — MEMORY.md routing table templateskills/core/templates/knowledge/entry-template.md — entry format referenceThis is what makes the repo "living." Execute after ANY significant action (analysis step, data ingestion, algorithm implementation, report generation):
ANALYSIS_MANIFEST.md, DATA_MANIFEST.md, etc.) with new/changed entries..living/decisions.md using the decision log template..living/learnings.md using the learning entry template. Required field: set mitigation_type to one of structural | convention | ambient-awareness (see template comments for definitions). Also fill structural_mitigation_candidate — if you can name a concrete test or invariant, upgrade the entry to structural. Knowledge promotion: If the learning is transferable (would help in any project), also append to the matching global domain file in ~/.claude/knowledge/{domain}.md with status: unreviewed. Use the structured entry template with a when_useful trigger condition.todo/TODO_REGISTRY.md (and create detailed todo/[item].md files for complex items).skills/core/scripts/validate_structure.py to confirm repo still conforms..living/learnings.md for recurring patterns (3+ related entries on the same topic). If found, check whether an equivalent convention already exists in .living/conventions.md — if so, append new Source: citations and refine the text only if materially improved. If no equivalent exists, add a new convention with Source: citations linking to the originating learnings. Do not create near-duplicate conventions..claude/last-session.md with a 5-section summary covering ALL work since session start. Use the session summary template:SESSION RESUME — Last session (YYYY-MM-DD HH:MM):
## What was worked on
- [Semantic summary of accomplishments — what was built/fixed/analyzed, not file lists]
## Key decisions made
- [Decision]: [rationale] (see .living/decisions.md for full context)
## Blockers & surprises
- [Resolved/Unresolved]: [what happened, resolution or current status]
## Current state
- Branch: X | Tests: N passing | [environment notes]
- [Key metrics, uncommitted changes, data state]
## Next steps
- [Actionable items with specific commands where relevant]
Full-session coverage: Run git log --since=<session-start-timestamp> and git diff --stat to capture all work since session start. If crystallization fires multiple times in a session, each write rebuilds the summary covering the entire session (cumulative, not incremental). The summary should get more expansive as the session progresses.
Mycelium ships optional hook scripts in hooks/ that enforce the post-action protocol automatically:
| Hook | Event | Purpose |
|---|---|---|
mycelium-health.sh | SessionStart | Loads .claude/last-session.md for session resume (agent + user); warns if .living/ is missing or incomplete; records session timestamp; triggers weekly knowledge audit if ~/.claude/knowledge/.last-audit is >7 days old |
mycelium-post-action.sh | PostToolUse (Bash) | Detects code execution and directs Claude to run the full post-action protocol |
mycelium-stop-check.sh | Stop | Checks .living/ was updated after significant work; warns if session summary (.claude/last-session.md) was not written |
Post-action enforcement: The PostToolUse hook detects Python/R/Jupyter execution in Bash calls (excluding tests, linting, pip, one-liners) and injects a mandatory directive for Claude to execute the full post-action protocol — saving outputs, updating manifests, and logging to .living/. It is debounced: fires once per work cycle, then stays silent until .living/ is updated (completing the cycle). This means Claude receives exactly one directive per burst of analysis work, not one per Bash call. The Stop hook serves as a safety net for non-analysis sessions.
Stop hook logic: The stop hook checks if mycelium-post-action.sh fired during the session (indicated by the presence of .claude/mycelium-reminded.tmp). If .living/ was not updated afterward, it warns. If .living/ was updated but .claude/last-session.md was not written (or is older than the session start), it emits a non-blocking warning reminding you to write the session summary. Read-only sessions, config-only sessions, and sessions without code execution are never checked.
Installation: Register the hooks in your project's .claude/settings.local.json:
{
"hooks": {
"SessionStart": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "/path/to/mycelium/skills/core/hooks/mycelium-health.sh"
}
]
}
],
"PostToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "/path/to/mycelium/skills/core/hooks/mycelium-post-action.sh"
}
]
}
],
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "/path/to/mycelium/skills/core/hooks/mycelium-stop-check.sh"
}
]
}
]
}
}
Replace /path/to/mycelium/ with the absolute path to your mycelium clone.
When work is dispatched to subagents (main context = coordination only):
.living/learnings.md and .living/decisions.md.claude/last-session.md using the 5-section session summary template (covering ALL work since session start, not just the latest batch — run git log --since=<session-start-ts> and git diff --stat to ground the summary in facts).living/ wasn't updated after significant work, catching sessions where the crystallization step was forgotten.Quick checks an agent or human can run to confirm mycelium is wired correctly:
| Check | Command / location | Expected |
|---|---|---|
| Hooks installed | cat .claude/settings.local.json | Five hooks: SessionStart→health, PostToolUse(Bash)→post-action, PostToolUse(Edit|Write)→activity-tracker, PostToolUse(Read)→read-tracker, Stop→stop-check |
| INDEX.md has knowledge summary | grep "BEGIN KNOWLEDGE SUMMARY" .living/INDEX.md | Match present |
| Read-access being logged | tail .claude/mycelium-read-access.log | Entries appearing whenever Claude reads .living/ files |
| MEMORY.md routing table present | grep "Global Knowledge Domains" ~/.claude/projects/*/memory/MEMORY.md | At least one match |
| Heuristic clusters populating | python3 skills/core/scripts/generate_index.py --living-dir .living/ --summary-heuristic --dry-run | Tag clusters with ≥2 entries shown |
| recall_lessons.py works | python3 skills/core/scripts/recall_lessons.py --living-dir .living/ --tag <known-tag> | Matching entries printed |
If any check fails, run python3 skills/core/scripts/migrate_existing_repos.py --repo . to bring the repo up to spec.
| Problem | Solution |
|---|---|
validate_structure.py fails after init | Check that all four top-level directories exist and each has its manifest (ANALYSIS_MANIFEST.md, etc.). Re-run init if needed. |
| Domain conventions conflict with core | Domain conventions take precedence. Update .living/conventions.md to document the override. |
.living/ directory missing | Run init mode to scaffold the living layer. Never create it manually — the script sets up required files. |
| Manifest entry format errors | Check skills/core/templates/dataset-manifest-entry.yaml or skills/core/templates/analysis-manifest-entry.yaml for the correct format. |
ENVIRONMENTS_INSTALLATIONS.md not found | Run init mode or create it manually following skills/core/references/environment-setup.md. |
| Crystallize finds no patterns | This is normal for young repos. Continue logging learnings and decisions — patterns emerge over time. |
| Install-convention can't find a domain | Check network/conventions/ for available packs. File a new-domain-request issue if your domain isn't covered. |