Diagnose and report on the health of an insight-wave workspace. Use this skill whenever the user mentions workspace status, health, diagnostics, or troubleshooting — including check workspace, is my workspace ok, something broke, why isn't my plugin working, diagnose workspace, verify workspace, or any situation where understanding the workspace state would help resolve a problem. Even if the user doesn't explicitly say status, trigger this skill when they describe symptoms that suggest a misconfigured workspace (missing env vars, plugins not found, themes not loading). This is the first skill to reach for when debugging workspace issues.
From cogni-workspacenpx claudepluginhub cogni-work/insight-wave --plugin cogni-workspaceThis skill is limited to using the following tools:
references/mcp-registry.mdGuides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Migrates code, prompts, and API calls from Claude Sonnet 4.0/4.5 or Opus 4.1 to Opus 4.5, updating model strings on Anthropic, AWS, GCP, Azure platforms.
Analyzes current state and user query to answer BMad questions or recommend the next skill(s) to use. Use when user asks for help, bmad help, what to do next, or what to start with in BMad.
Diagnose the health of an insight-wave workspace by checking its foundation files, environment variables, plugin registry, themes, dependencies, and MCP servers. The goal is to give the user a clear picture of what's working and what needs attention, with actionable fixes for every issue found.
Find the workspace using this priority:
$PROJECT_AGENTS_OPS_ROOT environment variableIf no .workspace-config.json exists at the resolved path, stop and tell the user no workspace was found. Suggest they run manage-workspace to create one and explain briefly what a workspace provides (centralized config, plugin discovery, shared themes).
Run all six checks, then present a single consolidated report. The checks are ordered by dependency — foundation must exist before environment makes sense, environment must be correct before plugins can be verified.
These files form the workspace skeleton. Without them, other checks can't run reliably.
| File | Required | What it does |
|---|---|---|
.workspace-config.json | Yes | Stores workspace metadata — version, language, registered plugins, timestamps. All other checks read from this file. |
.claude/settings.local.json | Yes | Environment variables that Claude Code auto-injects. Plugins use these to find each other's paths. |
.workspace-env.sh | No | Same variables exported for non-Claude contexts (Obsidian Terminal, VS Code tasks, CI/CD). Missing means shell-based tooling won't resolve plugin paths. |
.claude/output-styles/ | No | Behavioral anchors that shape Claude's communication style. Missing means default communication style. |
Read .workspace-config.json to extract: version, language, installed_plugins, created_at, updated_at.
If a required file is missing: report CRITICAL and suggest manage-workspace. Skip checks that depend on the missing file rather than producing misleading results.
Environment variables are the wiring that lets plugins find each other. A broken variable means a plugin can't locate its data directory or discover sibling plugins.
Verify these core variables exist and point to real directories:
PROJECT_AGENTS_OPS_ROOT — workspace rootCOGNI_WORKSPACE_ROOT — shared workspace data directoryThen for each plugin listed in .workspace-config.json, verify its computed variables:
COGNI_{SUFFIX}_ROOT or PLUGIN_{SUFFIX}_ROOT — the plugin's data directoryCOGNI_{SUFFIX}_PLUGIN or PLUGIN_{SUFFIX}_PLUGIN — the plugin's install pathRead the actual values from .claude/settings.local.json (the env object) and check that each path exists on disk. Report:
Plugins can drift out of sync — a user might install a new plugin without running manage-workspace, or uninstall one without cleaning up the config. This check catches that drift.
Run plugin discovery:
bash ${CLAUDE_PLUGIN_ROOT}/scripts/discover-plugins.sh
Compare the discovered plugins against installed_plugins in .workspace-config.json:
manage-workspace to clean up the stale registration.manage-workspace to wire it in.If discover-plugins.sh returns "success": false, report the error from data.error and note that plugin discovery couldn't complete.
Themes let visual plugins (slides, big pictures, web narratives) share a consistent look. Missing themes don't break anything, but they limit visual output options.
Scan ${COGNI_WORKSPACE_ROOT}/themes/ (skip _template):
theme.md contains "Color Palette" and "Typography" sections (these are the minimum viable sections visual plugins look for)_template/ exists (needed to create new themes)External tools that scripts rely on. Required dependencies block core functionality; optional ones limit specific features.
Run:
bash ${CLAUDE_PLUGIN_ROOT}/scripts/check-dependencies.sh
The script returns JSON with each tool's availability and version. Report:
brew install jq, etc.).If check-dependencies.sh returns "success": false, report which required tools are missing.
MCP servers power visual rendering (Excalidraw, Pencil), browser automation (claude-in-chrome),
and other capabilities. Plugins declare their required MCPs in .mcp.json files —
Desktop/Cowork auto-loads them when the plugin is installed. This check verifies that
required MCPs are actually available in the current session.
Read references/mcp-registry.md for the full list of ecosystem MCPs and which plugins
provide them.
Detection approach: Use ToolSearch to probe for MCP tool prefixes. For each known
MCP server, search for one representative tool:
| MCP Server | Probe tool | Provider plugin |
|---|---|---|
excalidraw | mcp__excalidraw__describe_scene | cogni-visual, cogni-portfolio |
excalidraw_sketch | mcp__excalidraw_sketch__read_me | cogni-visual |
claude-in-chrome | mcp__claude-in-chrome__tabs_context_mcp | cogni-claims, cogni-help, cogni-website, cogni-workspace |
pencil | mcp__pencil__get_editor_state | Pencil desktop app (manual) |
For each MCP, use ToolSearch with select: prefix to check if the tool exists.
If ToolSearch returns the tool definition, the MCP is loaded. If it returns no match,
the MCP is not available.
Report format:
Only check MCPs for plugins that are actually installed (cross-reference with the plugin registry from Check 3). Don't warn about MCPs for plugins the user hasn't installed.
Present results as a compact summary. Use OK / WARNING / CRITICAL status per category:
Workspace Status: /path/to/workspace
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Foundation: OK | 4/4 files present
Environment: OK | 12 vars set, 0 missing
Plugins: OK | 5 registered, 5 installed
Themes: OK | 3 themes available
Dependencies: OK | 2/2 required, 3/3 optional
MCP Servers: OK | 3/3 loaded (1 manual)
Language: EN | Last updated: 2026-03-04
Expand any category that isn't OK with specifics and a fix:
Plugins: WARNING | 5 registered, 6 installed
New: cogni-narrative (installed but not registered)
-> Run manage-workspace to register it
Environment: WARNING | 12 vars set, 2 broken
Broken: COGNI_NARRATIVE_ROOT -> /path/does/not/exist
Broken: COGNI_NARRATIVE_PLUGIN -> /path/does/not/exist
-> Run manage-workspace to refresh environment variables
Every issue should end with a concrete next step — either a skill to run (manage-workspace, manage-themes) or a command to execute.