[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M77S62YT7JAPCGS29MA8D6RY":3,"skill-same:01M77S62YT7JAPCGS29MA8D6RY":83},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":43,"commitSha":44,"skillDirectory":45,"forksCount":46,"repositoryHtmlUrl":47,"repositoryHomepageUrl":6,"ownerHtmlUrl":48,"ownerBlogUrl":49,"ownerDescription":6,"updatedAt":50,"install":51,"resources":64},"01M77S62YT7JAPCGS29MA8D6RY","neuroskill-bci",null,"Connect to a running NeuroSkill instance and incorporate the user's real-time cognitive and emotional state (focus, relaxation, mood, cognitive load, drowsiness, heart rate, HRV, sleep staging, and 40+ derived EXG scores) into responses. Requires a BCI wearable (Muse 2\u002FS or OpenBCI) and the NeuroSkill desktop app running locally.","vdcworkshop\u002FSkills-Catalog","vdcworkshop","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F275270998?v=4","01M77R8FXSKYTB2X9SSVJN7ZRZ","αtef βouafif","01M77R8FYGECN2YWM6WVBVPMGS",1,"MIT","https:\u002F\u002Fgithub.com\u002Fvdcworkshop\u002FSkills-Catalog\u002Fblob\u002Fmain\u002F02 Business\u002F05 Health & Fitness\u002Fneuroskill-bci\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: neuroskill-bci\ndescription: >\n  Connect to a running NeuroSkill instance and incorporate the user's real-time\n  cognitive and emotional state (focus, relaxation, mood, cognitive load, drowsiness,\n  heart rate, HRV, sleep staging, and 40+ derived EXG scores) into responses.\n  Requires a BCI wearable (Muse 2\u002FS or OpenBCI) and the NeuroSkill desktop app\n  running locally.\nplatforms: [linux, macos, windows]\nversion: 1.0.0\nauthor: Hermes Agent + Nous Research\nlicense: MIT\nmetadata:\n  hermes:\n    tags: [BCI, neurofeedback, health, focus, EEG, cognitive-state, biometrics, neuroskill]\n    category: health\n    related_skills: []\n---\n\n# NeuroSkill BCI Integration\n\nConnect Hermes to a running [NeuroSkill](https:\u002F\u002Fneuroskill.com\u002F) instance to read\nreal-time brain and body metrics from a BCI wearable. Use this to give\ncognitively-aware responses, suggest interventions, and track mental performance\nover time.\n\n> **⚠️ Research Use Only** — NeuroSkill is an open-source research tool. It is\n> NOT a medical device and has NOT been cleared by the FDA, CE, or any regulatory\n> body. Never use these metrics for clinical diagnosis or treatment.\n\nSee `references\u002Fmetrics.md` for the full metric reference, `references\u002Fprotocols.md`\nfor intervention protocols, and `references\u002Fapi.md` for the WebSocket\u002FHTTP API.\n\n---\n\n## Prerequisites\n\n- **Node.js 20+** installed (`node --version`)\n- **NeuroSkill desktop app** running with a connected BCI device\n- **BCI hardware**: Muse 2, Muse S, or OpenBCI (4-channel EEG + PPG + IMU via BLE)\n- `npx neuroskill status` returns data without errors\n\n### Verify Setup\n```bash\nnode --version                    # Must be 20+\nnpx neuroskill status             # Full system snapshot\nnpx neuroskill status --json      # Machine-parseable JSON\n```\n\nIf `npx neuroskill status` returns an error, tell the user:\n- Make sure the NeuroSkill desktop app is open\n- Ensure the BCI device is powered on and connected via Bluetooth\n- Check signal quality — green indicators in NeuroSkill (≥0.7 per electrode)\n- If `command not found`, install Node.js 20+\n\n---\n\n## CLI Reference: `npx neuroskill \u003Ccommand>`\n\nAll commands support `--json` (raw JSON, pipe-safe) and `--full` (human summary + JSON).\n\n| Command | Description |\n|---------|-------------|\n| `status` | Full system snapshot: device, scores, bands, ratios, sleep, history |\n| `session [N]` | Single session breakdown with first\u002Fsecond half trends (0=most recent) |\n| `sessions` | List all recorded sessions across all days |\n| `search` | ANN similarity search for neurally similar historical moments |\n| `compare` | A\u002FB session comparison with metric deltas and trend analysis |\n| `sleep [N]` | Sleep stage classification (Wake\u002FN1\u002FN2\u002FN3\u002FREM) with analysis |\n| `label \"text\"` | Create a timestamped annotation at the current moment |\n| `search-labels \"query\"` | Semantic vector search over past labels |\n| `interactive \"query\"` | Cross-modal 4-layer graph search (text → EXG → labels) |\n| `listen` | Real-time event streaming (default 5s, set `--seconds N`) |\n| `umap` | 3D UMAP projection of session embeddings |\n| `calibrate` | Open calibration window and start a profile |\n| `timer` | Launch focus timer (Pomodoro\u002FDeep Work\u002FShort Focus presets) |\n| `notify \"title\" \"body\"` | Send an OS notification via the NeuroSkill app |\n| `raw '{json}'` | Raw JSON passthrough to the server |\n\n### Global Flags\n| Flag | Description |\n|------|-------------|\n| `--json` | Raw JSON output (no ANSI, pipe-safe) |\n| `--full` | Human summary + colorized JSON |\n| `--port \u003CN>` | Override server port (default: auto-discover, usually 8375) |\n| `--ws` | Force WebSocket transport |\n| `--http` | Force HTTP transport |\n| `--k \u003CN>` | Nearest neighbors count (search, search-labels) |\n| `--seconds \u003CN>` | Duration for listen (default: 5) |\n| `--trends` | Show per-session metric trends (sessions) |\n| `--dot` | Graphviz DOT output (interactive) |\n\n---\n\n## 1. Checking Current State\n\n### Get Live Metrics\n```bash\nnpx neuroskill status --json\n```\n\n**Always use `--json`** for reliable parsing. The default output is colorized\nhuman-readable text.\n\n### Key Fields in the Response\n\nThe `scores` object contains all live metrics (0–1 scale unless noted):\n\n```jsonc\n{\n  \"scores\": {\n    \"focus\": 0.70,           \u002F\u002F β \u002F (α + θ) — sustained attention\n    \"relaxation\": 0.40,      \u002F\u002F α \u002F (β + θ) — calm wakefulness\n    \"engagement\": 0.60,      \u002F\u002F active mental investment\n    \"meditation\": 0.52,      \u002F\u002F alpha + stillness + HRV coherence\n    \"mood\": 0.55,            \u002F\u002F composite from FAA, TAR, BAR\n    \"cognitive_load\": 0.33,  \u002F\u002F frontal θ \u002F temporal α · f(FAA, TBR)\n    \"drowsiness\": 0.10,      \u002F\u002F TAR + TBR + falling spectral centroid\n    \"hr\": 68.2,              \u002F\u002F heart rate in bpm (from PPG)\n    \"snr\": 14.3,             \u002F\u002F signal-to-noise ratio in dB\n    \"stillness\": 0.88,       \u002F\u002F 0–1; 1 = perfectly still\n    \"faa\": 0.042,            \u002F\u002F Frontal Alpha Asymmetry (+ = approach)\n    \"tar\": 0.56,             \u002F\u002F Theta\u002FAlpha Ratio\n    \"bar\": 0.53,             \u002F\u002F Beta\u002FAlpha Ratio\n    \"tbr\": 1.06,             \u002F\u002F Theta\u002FBeta Ratio (ADHD proxy)\n    \"apf\": 10.1,             \u002F\u002F Alpha Peak Frequency in Hz\n    \"coherence\": 0.614,      \u002F\u002F inter-hemispheric coherence\n    \"bands\": {\n      \"rel_delta\": 0.28, \"rel_theta\": 0.18,\n      \"rel_alpha\": 0.32, \"rel_beta\": 0.17, \"rel_gamma\": 0.05\n    }\n  }\n}\n```\n\nAlso includes: `device` (state, battery, firmware), `signal_quality` (per-electrode 0–1),\n`session` (duration, epochs), `embeddings`, `labels`, `sleep` summary, and `history`.\n\n### Interpreting the Output\n\nParse the JSON and translate metrics into natural language. Never report raw\nnumbers alone — always give them meaning:\n\n**DO:**\n> \"Your focus is solid right now at 0.70 — that's flow state territory. Heart\n> rate is steady at 68 bpm and your FAA is positive, which suggests good\n> approach motivation. Great time to tackle something complex.\"\n\n**DON'T:**\n> \"Focus: 0.70, Relaxation: 0.40, HR: 68\"\n\nKey interpretation thresholds (see `references\u002Fmetrics.md` for the full guide):\n- **Focus > 0.70** → flow state territory, protect it\n- **Focus \u003C 0.40** → suggest a break or protocol\n- **Drowsiness > 0.60** → fatigue warning, micro-sleep risk\n- **Relaxation \u003C 0.30** → stress intervention needed\n- **Cognitive Load > 0.70 sustained** → mind dump or break\n- **TBR > 1.5** → theta-dominant, reduced executive control\n- **FAA \u003C 0** → withdrawal\u002Fnegative affect — consider FAA rebalancing\n- **SNR \u003C 3 dB** → unreliable signal, suggest electrode repositioning\n\n---\n\n## 2. Session Analysis\n\n### Single Session Breakdown\n```bash\nnpx neuroskill session --json         # most recent session\nnpx neuroskill session 1 --json       # previous session\nnpx neuroskill session 0 --json | jq '{focus: .metrics.focus, trend: .trends.focus}'\n```\n\nReturns full metrics with **first-half vs second-half trends** (`\"up\"`, `\"down\"`, `\"flat\"`).\nUse this to describe how a session evolved:\n\n> \"Your focus started at 0.64 and climbed to 0.76 by the end — a clear upward trend.\n> Cognitive load dropped from 0.38 to 0.28, suggesting the task became more automatic\n> as you settled in.\"\n\n### List All Sessions\n```bash\nnpx neuroskill sessions --json\nnpx neuroskill sessions --trends      # show per-session metric trends\n```\n\n---\n\n## 3. Historical Search\n\n### Neural Similarity Search\n```bash\nnpx neuroskill search --json                    # auto: last session, k=5\nnpx neuroskill search --k 10 --json             # 10 nearest neighbors\nnpx neuroskill search --start \u003CUTC> --end \u003CUTC> --json\n```\n\nFinds moments in history that are neurally similar using HNSW approximate\nnearest-neighbor search over 128-D ZUNA embeddings. Returns distance statistics,\ntemporal distribution (hour of day), and top matching days.\n\nUse this when the user asks:\n- \"When was I last in a state like this?\"\n- \"Find my best focus sessions\"\n- \"When do I usually crash in the afternoon?\"\n\n### Semantic Label Search\n```bash\nnpx neuroskill search-labels \"deep focus\" --k 10 --json\nnpx neuroskill search-labels \"stress\" --json | jq '[.results[].EXG_metrics.tbr]'\n```\n\nSearches label text using vector embeddings (Xenova\u002Fbge-small-en-v1.5). Returns\nmatching labels with their associated EXG metrics at the time of labeling.\n\n### Cross-Modal Graph Search\n```bash\nnpx neuroskill interactive \"deep focus\" --json\nnpx neuroskill interactive \"deep focus\" --dot | dot -Tsvg > graph.svg\n```\n\n4-layer graph: query → text labels → EXG points → nearby labels. Use `--k-text`,\n`--k-EXG`, `--reach \u003Cminutes>` to tune.\n\n---\n\n## 4. Session Comparison\n```bash\nnpx neuroskill compare --json                   # auto: last 2 sessions\nnpx neuroskill compare --a-start \u003CUTC> --a-end \u003CUTC> --b-start \u003CUTC> --b-end \u003CUTC> --json\n```\n\nReturns metric deltas with absolute change, percentage change, and direction for\n~50 metrics. Also includes `insights.improved[]` and `insights.declined[]` arrays,\nsleep staging for both sessions, and a UMAP job ID.\n\nInterpret comparisons with context — mention trends, not just deltas:\n> \"Yesterday you had two strong focus blocks (10am and 2pm). Today you've had one\n> starting around 11am that's still going. Your overall engagement is higher today\n> but there have been more stress spikes — your stress index jumped 15% and\n> FAA dipped negative more often.\"\n\n```bash\n# Sort metrics by improvement percentage\nnpx neuroskill compare --json | jq '.insights.deltas | to_entries | sort_by(.value.pct) | reverse'\n```\n\n---\n\n## 5. Sleep Data\n```bash\nnpx neuroskill sleep --json                     # last 24 hours\nnpx neuroskill sleep 0 --json                   # most recent sleep session\nnpx neuroskill sleep --start \u003CUTC> --end \u003CUTC> --json\n```\n\nReturns epoch-by-epoch sleep staging (5-second windows) with analysis:\n- **Stage codes**: 0=Wake, 1=N1, 2=N2, 3=N3 (deep), 4=REM\n- **Analysis**: efficiency_pct, onset_latency_min, rem_latency_min, bout counts\n- **Healthy targets**: N3 15–25%, REM 20–25%, efficiency >85%, onset \u003C20 min\n\n```bash\nnpx neuroskill sleep --json | jq '.summary | {n3: .n3_epochs, rem: .rem_epochs}'\nnpx neuroskill sleep --json | jq '.analysis.efficiency_pct'\n```\n\nUse this when the user mentions sleep, tiredness, or recovery.\n\n---\n\n## 6. Labeling Moments\n```bash\nnpx neuroskill label \"breakthrough\"\nnpx neuroskill label \"studying algorithms\"\nnpx neuroskill label \"post-meditation\"\nnpx neuroskill label --json \"focus block start\"   # returns label_id\n```\n\nAuto-label moments when:\n- User reports a breakthrough or insight\n- User starts a new task type (e.g., \"switching to code review\")\n- User completes a significant protocol\n- User asks you to mark the current moment\n- A notable state transition occurs (entering\u002Fleaving flow)\n\nLabels are stored in a database and indexed for later retrieval via `search-labels`\nand `interactive` commands.\n\n---\n\n## 7. Real-Time Streaming\n```bash\nnpx neuroskill listen --seconds 30 --json\nnpx neuroskill listen --seconds 5 --json | jq '[.[] | select(.event == \"scores\")]'\n```\n\nStreams live WebSocket events (EXG, PPG, IMU, scores, labels) for the specified\nduration. Requires WebSocket connection (not available with `--http`).\n\nUse this for continuous monitoring scenarios or to observe metric changes in real-time\nduring a protocol.\n\n---\n\n## 8. UMAP Visualization\n```bash\nnpx neuroskill umap --json                      # auto: last 2 sessions\nnpx neuroskill umap --a-start \u003CUTC> --a-end \u003CUTC> --b-start \u003CUTC> --b-end \u003CUTC> --json\n```\n\nGPU-accelerated 3D UMAP projection of ZUNA embeddings. The `separation_score`\nindicates how neurally distinct two sessions are:\n- **> 1.5** → Sessions are neurally distinct (different brain states)\n- **\u003C 0.5** → Similar brain states across both sessions\n\n---\n\n## 9. Proactive State Awareness\n\n### Session Start Check\nAt the beginning of a session, optionally run a status check if the user mentions\nthey're wearing their device or asks about their state:\n```bash\nnpx neuroskill status --json\n```\n\nInject a brief state summary:\n> \"Quick check-in: focus is building at 0.62, relaxation is good at 0.55, and your\n> FAA is positive — approach motivation is engaged. Looks like a solid start.\"\n\n### When to Proactively Mention State\n\nMention cognitive state **only** when:\n- User explicitly asks (\"How am I doing?\", \"Check my focus\")\n- User reports difficulty concentrating, stress, or fatigue\n- A critical threshold is crossed (drowsiness > 0.70, focus \u003C 0.30 sustained)\n- User is about to do something cognitively demanding and asks for readiness\n\n**Do NOT** interrupt flow state to report metrics. If focus > 0.75, protect the\nsession — silence is the correct response.\n\n---\n\n## 10. Suggesting Protocols\n\nWhen metrics indicate a need, suggest a protocol from `references\u002Fprotocols.md`.\nAlways ask before starting — never interrupt flow state:\n\n> \"Your focus has been declining for the past 15 minutes and TBR is climbing past\n> 1.5 — signs of theta dominance and mental fatigue. Want me to walk you through\n> a Theta-Beta Neurofeedback Anchor? It's a 90-second exercise that uses rhythmic\n> counting and breath to suppress theta and lift beta.\"\n\nKey triggers:\n- **Focus \u003C 0.40, TBR > 1.5** → Theta-Beta Neurofeedback Anchor or Box Breathing\n- **Relaxation \u003C 0.30, stress_index high** → Cardiac Coherence or 4-7-8 Breathing\n- **Cognitive Load > 0.70 sustained** → Cognitive Load Offload (mind dump)\n- **Drowsiness > 0.60** → Ultradian Reset or Wake Reset\n- **FAA \u003C 0 (negative)** → FAA Rebalancing\n- **Flow State (focus > 0.75, engagement > 0.70)** → Do NOT interrupt\n- **High stillness + headache_index** → Neck Release Sequence\n- **Low RMSSD (\u003C 25ms)** → Vagal Toning\n\n---\n\n## 11. Additional Tools\n\n### Focus Timer\n```bash\nnpx neuroskill timer --json\n```\nLaunches the Focus Timer window with Pomodoro (25\u002F5), Deep Work (50\u002F10), or\nShort Focus (15\u002F5) presets.\n\n### Calibration\n```bash\nnpx neuroskill calibrate\nnpx neuroskill calibrate --profile \"Eyes Open\"\n```\nOpens the calibration window. Useful when signal quality is poor or the user\nwants to establish a personalized baseline.\n\n### OS Notifications\n```bash\nnpx neuroskill notify \"Break Time\" \"Your focus has been declining for 20 minutes\"\n```\n\n### Raw JSON Passthrough\n```bash\nnpx neuroskill raw '{\"command\":\"status\"}' --json\n```\nFor any server command not yet mapped to a CLI subcommand.\n\n---\n\n## Error Handling\n\n| Error | Likely Cause | Fix |\n|-------|-------------|-----|\n| `npx neuroskill status` hangs | NeuroSkill app not running | Open NeuroSkill desktop app |\n| `device.state: \"disconnected\"` | BCI device not connected | Check Bluetooth, device battery |\n| All scores return 0 | Poor electrode contact | Reposition headband, moisten electrodes |\n| `signal_quality` values \u003C 0.7 | Loose electrodes | Adjust fit, clean electrode contacts |\n| SNR \u003C 3 dB | Noisy signal | Minimize head movement, check environment |\n| `command not found: npx` | Node.js not installed | Install Node.js 20+ |\n\n---\n\n## Example Interactions\n\n**\"How am I doing right now?\"**\n```bash\nnpx neuroskill status --json\n```\n→ Interpret scores naturally, mentioning focus, relaxation, mood, and any notable\n  ratios (FAA, TBR). Suggest an action only if metrics indicate a need.\n\n**\"I can't concentrate\"**\n```bash\nnpx neuroskill status --json\n```\n→ Check if metrics confirm it (high theta, low beta, rising TBR, high drowsiness).\n→ If confirmed, suggest an appropriate protocol from `references\u002Fprotocols.md`.\n→ If metrics look fine, the issue may be motivational rather than neurological.\n\n**\"Compare my focus today vs yesterday\"**\n```bash\nnpx neuroskill compare --json\n```\n→ Interpret trends, not just numbers. Mention what improved, what declined, and\n  possible causes.\n\n**\"When was I last in a flow state?\"**\n```bash\nnpx neuroskill search-labels \"flow\" --json\nnpx neuroskill search --json\n```\n→ Report timestamps, associated metrics, and what the user was doing (from labels).\n\n**\"How did I sleep?\"**\n```bash\nnpx neuroskill sleep --json\n```\n→ Report sleep architecture (N3%, REM%, efficiency), compare to healthy targets,\n  and note any issues (high wake epochs, low REM).\n\n**\"Mark this moment — I just had a breakthrough\"**\n```bash\nnpx neuroskill label \"breakthrough\"\n```\n→ Confirm label saved. Optionally note the current metrics to remember the state.\n\n---\n\n## References\n\n- [NeuroSkill Paper — arXiv:2603.03212](https:\u002F\u002Farxiv.org\u002Fabs\u002F2603.03212) (Kosmyna & Hauptmann, MIT Media Lab)\n- [NeuroSkill Desktop App](https:\u002F\u002Fgithub.com\u002FNeuroSkill-com\u002Fskill) (GPLv3)\n- [NeuroLoop CLI Companion](https:\u002F\u002Fgithub.com\u002FNeuroSkill-com\u002Fneuroloop) (GPLv3)\n- [MIT Media Lab Project](https:\u002F\u002Fwww.media.mit.edu\u002Fprojects\u002Fneuroskill\u002Foverview\u002F)\n","# NeuroSkill BCI Integration\n\nConnect Hermes to a running [NeuroSkill](https:\u002F\u002Fneuroskill.com\u002F) instance to read\nreal-time brain and body metrics from a BCI wearable. Use this to give\ncognitively-aware responses, suggest interventions, and track mental performance\nover time.\n\n> **⚠️ Research Use Only** — NeuroSkill is an open-source research tool. It is\n> NOT a medical device and has NOT been cleared by the FDA, CE, or any regulatory\n> body. Never use these metrics for clinical diagnosis or treatment.\n\nSee `references\u002Fmetrics.md` for the full metric reference, `references\u002Fprotocols.md`\nfor intervention protocols, and `references\u002Fapi.md` for the WebSocket\u002FHTTP API.\n\n---\n\n## Prerequisites\n\n- **Node.js 20+** installed (`node --version`)\n- **NeuroSkill desktop app** running with a connected BCI device\n- **BCI hardware**: Muse 2, Muse S, or OpenBCI (4-channel EEG + PPG + IMU via BLE)\n- `npx neuroskill status` returns data without errors\n\n### Verify Setup\n```bash\nnode --version                    # Must be 20+\nnpx neuroskill status             # Full system snapshot\nnpx neuroskill status --json      # Machine-parseable JSON\n```\n\nIf `npx neuroskill status` returns an error, tell the user:\n- Make sure the NeuroSkill desktop app is open\n- Ensure the BCI device is powered on and connected via Bluetooth\n- Check signal quality — green indicators in NeuroSkill (≥0.7 per electrode)\n- If `command not found`, install Node.js 20+\n\n---\n\n## CLI Reference: `npx neuroskill \u003Ccommand>`\n\nAll commands support `--json` (raw JSON, pipe-safe) and `--full` (human summary + JSON).\n\n| Command | Description |\n|---------|-------------|\n| `status` | Full system snapshot: device, scores, bands, ratios, sleep, history |\n| `session [N]` | Single session breakdown with first\u002Fsecond half trends (0=most recent) |\n| `sessions` | List all recorded sessions across all days |\n| `search` | ANN similarity search for neurally similar historical moments |\n| `compare` | A\u002FB session comparison with metric deltas and trend analysis |\n| `sleep [N]` | Sleep stage classification (Wake\u002FN1\u002FN2\u002FN3\u002FREM) with analysis |\n| `label \"text\"` | Create a timestamped annotation at the current moment |\n| `search-labels \"query\"` | Semantic vector search over past labels |\n| `interactive \"query\"` | Cross-modal 4-layer graph search (text → EXG → labels) |\n| `listen` | Real-time event streaming (default 5s, set `--seconds N`) |\n| `umap` | 3D UMAP projection of session embeddings |\n| `calibrate` | Open calibration window and start a profile |\n| `timer` | Launch focus timer (Pomodoro\u002FDeep Work\u002FShort Focus presets) |\n| `notify \"title\" \"body\"` | Send an OS notification via the NeuroSkill app |\n| `raw '{json}'` | Raw JSON passthrough to the server |\n\n### Global Flags\n| Flag | Description |\n|------|-------------|\n| `--json` | Raw JSON output (no ANSI, pipe-safe) |\n| `--full` | Human summary + colorized JSON |\n| `--port \u003CN>` | Override server port (default: auto-discover, usually 8375) |\n| `--ws` | Force WebSocket transport |\n| `--http` | Force HTTP transport |\n| `--k \u003CN>` | Nearest neighbors count (search, search-labels) |\n| `--seconds \u003CN>` | Duration for listen (default: 5) |\n| `--trends` | Show per-session metric trends (sessions) |\n| `--dot` | Graphviz DOT output (interactive) |\n\n---\n\n## 1. Checking Current State\n\n### Get Live Metrics\n```bash\nnpx neuroskill status --json\n```\n\n**Always use `--json`** for reliable parsing. The default output is colorized\nhuman-readable text.\n\n### Key Fields in the Response\n\nThe `scores` object contains all live metrics (0–1 scale unless noted):\n\n```jsonc\n{\n  \"scores\": {\n    \"focus\": 0.70,           \u002F\u002F β \u002F (α + θ) — sustained attention\n    \"relaxation\": 0.40,      \u002F\u002F α \u002F (β + θ) — calm wakefulness\n    \"engagement\": 0.60,      \u002F\u002F active mental investment\n    \"meditation\": 0.52,      \u002F\u002F alpha + stillness + HRV coherence\n    \"mood\": 0.55,            \u002F\u002F composite from FAA, TAR, BAR\n    \"cognitive_load\": 0.33,  \u002F\u002F frontal θ \u002F temporal α · f(FAA, TBR)\n    \"drowsiness\": 0.10,      \u002F\u002F TAR + TBR + falling spectral centroid\n    \"hr\": 68.2,              \u002F\u002F heart rate in bpm (from PPG)\n    \"snr\": 14.3,             \u002F\u002F signal-to-noise ratio in dB\n    \"stillness\": 0.88,       \u002F\u002F 0–1; 1 = perfectly still\n    \"faa\": 0.042,            \u002F\u002F Frontal Alpha Asymmetry (+ = approach)\n    \"tar\": 0.56,             \u002F\u002F Theta\u002FAlpha Ratio\n    \"bar\": 0.53,             \u002F\u002F Beta\u002FAlpha Ratio\n    \"tbr\": 1.06,             \u002F\u002F Theta\u002FBeta Ratio (ADHD proxy)\n    \"apf\": 10.1,             \u002F\u002F Alpha Peak Frequency in Hz\n    \"coherence\": 0.614,      \u002F\u002F inter-hemispheric coherence\n    \"bands\": {\n      \"rel_delta\": 0.28, \"rel_theta\": 0.18,\n      \"rel_alpha\": 0.32, \"rel_beta\": 0.17, \"rel_gamma\": 0.05\n    }\n  }\n}\n```\n\nAlso includes: `device` (state, battery, firmware), `signal_quality` (per-electrode 0–1),\n`session` (duration, epochs), `embeddings`, `labels`, `sleep` summary, and `history`.\n\n### Interpreting the Output\n\nParse the JSON and translate metrics into natural language. Never report raw\nnumbers alone — always give them meaning:\n\n**DO:**\n> \"Your focus is solid right now at 0.70 — that's flow state territory. Heart\n> rate is steady at 68 bpm and your FAA is positive, which suggests good\n> approach motivation. Great time to tackle something complex.\"\n\n**DON'T:**\n> \"Focus: 0.70, Relaxation: 0.40, HR: 68\"\n\nKey interpretation thresholds (see `references\u002Fmetrics.md` for the full guide):\n- **Focus > 0.70** → flow state territory, protect it\n- **Focus \u003C 0.40** → suggest a break or protocol\n- **Drowsiness > 0.60** → fatigue warning, micro-sleep risk\n- **Relaxation \u003C 0.30** → stress intervention needed\n- **Cognitive Load > 0.70 sustained** → mind dump or break\n- **TBR > 1.5** → theta-dominant, reduced executive control\n- **FAA \u003C 0** → withdrawal\u002Fnegative affect — consider FAA rebalancing\n- **SNR \u003C 3 dB** → unreliable signal, suggest electrode repositioning\n\n---\n\n## 2. Session Analysis\n\n### Single Session Breakdown\n```bash\nnpx neuroskill session --json         # most recent session\nnpx neuroskill session 1 --json       # previous session\nnpx neuroskill session 0 --json | jq '{focus: .metrics.focus, trend: .trends.focus}'\n```\n\nReturns full metrics with **first-half vs second-half trends** (`\"up\"`, `\"down\"`, `\"flat\"`).\nUse this to describe how a session evolved:\n\n> \"Your focus started at 0.64 and climbed to 0.76 by the end — a clear upward trend.\n> Cognitive load dropped from 0.38 to 0.28, suggesting the task became more automatic\n> as you settled in.\"\n\n### List All Sessions\n```bash\nnpx neuroskill sessions --json\nnpx neuroskill sessions --trends      # show per-session metric trends\n```\n\n---\n\n## 3. Historical Search\n\n### Neural Similarity Search\n```bash\nnpx neuroskill search --json                    # auto: last session, k=5\nnpx neuroskill search --k 10 --json             # 10 nearest neighbors\nnpx neuroskill search --start \u003CUTC> --end \u003CUTC> --json\n```\n\nFinds moments in history that are neurally similar using HNSW approximate\nnearest-neighbor search over 128-D ZUNA embeddings. Returns distance statistics,\ntemporal distribution (hour of day), and top matching days.\n\nUse this when the user asks:\n- \"When was I last in a state like this?\"\n- \"Find my best focus sessions\"\n- \"When do I usually crash in the afternoon?\"\n\n### Semantic Label Search\n```bash\nnpx neuroskill search-labels \"deep focus\" --k 10 --json\nnpx neuroskill search-labels \"stress\" --json | jq '[.results[].EXG_metrics.tbr]'\n```\n\nSearches label text using vector embeddings (Xenova\u002Fbge-small-en-v1.5). Returns\nmatching labels with their associated EXG metrics at the time of labeling.\n\n### Cross-Modal Graph Search\n```bash\nnpx neuroskill interactive \"deep focus\" --json\nnpx neuroskill interactive \"deep focus\" --dot | dot -Tsvg > graph.svg\n```\n\n4-layer graph: query → text labels → EXG points → nearby labels. Use `--k-text`,\n`--k-EXG`, `--reach \u003Cminutes>` to tune.\n\n---\n\n## 4. Session Comparison\n```bash\nnpx neuroskill compare --json                   # auto: last 2 sessions\nnpx neuroskill compare --a-start \u003CUTC> --a-end \u003CUTC> --b-start \u003CUTC> --b-end \u003CUTC> --json\n```\n\nReturns metric deltas with absolute change, percentage change, and direction for\n~50 metrics. Also includes `insights.improved[]` and `insights.declined[]` arrays,\nsleep staging for both sessions, and a UMAP job ID.\n\nInterpret comparisons with context — mention trends, not just deltas:\n> \"Yesterday you had two strong focus blocks (10am and 2pm). Today you've had one\n> starting around 11am that's still going. Your overall engagement is higher today\n> but there have been more stress spikes — your stress index jumped 15% and\n> FAA dipped negative more often.\"\n\n```bash\n# Sort metrics by improvement percentage\nnpx neuroskill compare --json | jq '.insights.deltas | to_entries | sort_by(.value.pct) | reverse'\n```\n\n---\n\n## 5. Sleep Data\n```bash\nnpx neuroskill sleep --json                     # last 24 hours\nnpx neuroskill sleep 0 --json                   # most recent sleep session\nnpx neuroskill sleep --start \u003CUTC> --end \u003CUTC> --json\n```\n\nReturns epoch-by-epoch sleep staging (5-second windows) with analysis:\n- **Stage codes**: 0=Wake, 1=N1, 2=N2, 3=N3 (deep), 4=REM\n- **Analysis**: efficiency_pct, onset_latency_min, rem_latency_min, bout counts\n- **Healthy targets**: N3 15–25%, REM 20–25%, efficiency >85%, onset \u003C20 min\n\n```bash\nnpx neuroskill sleep --json | jq '.summary | {n3: .n3_epochs, rem: .rem_epochs}'\nnpx neuroskill sleep --json | jq '.analysis.efficiency_pct'\n```\n\nUse this when the user mentions sleep, tiredness, or recovery.\n\n---\n\n## 6. Labeling Moments\n```bash\nnpx neuroskill label \"breakthrough\"\nnpx neuroskill label \"studying algorithms\"\nnpx neuroskill label \"post-meditation\"\nnpx neuroskill label --json \"focus block start\"   # returns label_id\n```\n\nAuto-label moments when:\n- User reports a breakthrough or insight\n- User starts a new task type (e.g., \"switching to code review\")\n- User completes a significant protocol\n- User asks you to mark the current moment\n- A notable state transition occurs (entering\u002Fleaving flow)\n\nLabels are stored in a database and indexed for later retrieval via `search-labels`\nand `interactive` commands.\n\n---\n\n## 7. Real-Time Streaming\n```bash\nnpx neuroskill listen --seconds 30 --json\nnpx neuroskill listen --seconds 5 --json | jq '[.[] | select(.event == \"scores\")]'\n```\n\nStreams live WebSocket events (EXG, PPG, IMU, scores, labels) for the specified\nduration. Requires WebSocket connection (not available with `--http`).\n\nUse this for continuous monitoring scenarios or to observe metric changes in real-time\nduring a protocol.\n\n---\n\n## 8. UMAP Visualization\n```bash\nnpx neuroskill umap --json                      # auto: last 2 sessions\nnpx neuroskill umap --a-start \u003CUTC> --a-end \u003CUTC> --b-start \u003CUTC> --b-end \u003CUTC> --json\n```\n\nGPU-accelerated 3D UMAP projection of ZUNA embeddings. The `separation_score`\nindicates how neurally distinct two sessions are:\n- **> 1.5** → Sessions are neurally distinct (different brain states)\n- **\u003C 0.5** → Similar brain states across both sessions\n\n---\n\n## 9. Proactive State Awareness\n\n### Session Start Check\nAt the beginning of a session, optionally run a status check if the user mentions\nthey're wearing their device or asks about their state:\n```bash\nnpx neuroskill status --json\n```\n\nInject a brief state summary:\n> \"Quick check-in: focus is building at 0.62, relaxation is good at 0.55, and your\n> FAA is positive — approach motivation is engaged. Looks like a solid start.\"\n\n### When to Proactively Mention State\n\nMention cognitive state **only** when:\n- User explicitly asks (\"How am I doing?\", \"Check my focus\")\n- User reports difficulty concentrating, stress, or fatigue\n- A critical threshold is crossed (drowsiness > 0.70, focus \u003C 0.30 sustained)\n- User is about to do something cognitively demanding and asks for readiness\n\n**Do NOT** interrupt flow state to report metrics. If focus > 0.75, protect the\nsession — silence is the correct response.\n\n---\n\n## 10. Suggesting Protocols\n\nWhen metrics indicate a need, suggest a protocol from `references\u002Fprotocols.md`.\nAlways ask before starting — never interrupt flow state:\n\n> \"Your focus has been declining for the past 15 minutes and TBR is climbing past\n> 1.5 — signs of theta dominance and mental fatigue. Want me to walk you through\n> a Theta-Beta Neurofeedback Anchor? It's a 90-second exercise that uses rhythmic\n> counting and breath to suppress theta and lift beta.\"\n\nKey triggers:\n- **Focus \u003C 0.40, TBR > 1.5** → Theta-Beta Neurofeedback Anchor or Box Breathing\n- **Relaxation \u003C 0.30, stress_index high** → Cardiac Coherence or 4-7-8 Breathing\n- **Cognitive Load > 0.70 sustained** → Cognitive Load Offload (mind dump)\n- **Drowsiness > 0.60** → Ultradian Reset or Wake Reset\n- **FAA \u003C 0 (negative)** → FAA Rebalancing\n- **Flow State (focus > 0.75, engagement > 0.70)** → Do NOT interrupt\n- **High stillness + headache_index** → Neck Release Sequence\n- **Low RMSSD (\u003C 25ms)** → Vagal Toning\n\n---\n\n## 11. Additional Tools\n\n### Focus Timer\n```bash\nnpx neuroskill timer --json\n```\nLaunches the Focus Timer window with Pomodoro (25\u002F5), Deep Work (50\u002F10), or\nShort Focus (15\u002F5) presets.\n\n### Calibration\n```bash\nnpx neuroskill calibrate\nnpx neuroskill calibrate --profile \"Eyes Open\"\n```\nOpens the calibration window. Useful when signal quality is poor or the user\nwants to establish a personalized baseline.\n\n### OS Notifications\n```bash\nnpx neuroskill notify \"Break Time\" \"Your focus has been declining for 20 minutes\"\n```\n\n### Raw JSON Passthrough\n```bash\nnpx neuroskill raw '{\"command\":\"status\"}' --json\n```\nFor any server command not yet mapped to a CLI subcommand.\n\n---\n\n## Error Handling\n\n| Error | Likely Cause | Fix |\n|-------|-------------|-----|\n| `npx neuroskill status` hangs | NeuroSkill app not running | Open NeuroSkill desktop app |\n| `device.state: \"disconnected\"` | BCI device not connected | Check Bluetooth, device battery |\n| All scores return 0 | Poor electrode contact | Reposition headband, moisten electrodes |\n| `signal_quality` values \u003C 0.7 | Loose electrodes | Adjust fit, clean electrode contacts |\n| SNR \u003C 3 dB | Noisy signal | Minimize head movement, check environment |\n| `command not found: npx` | Node.js not installed | Install Node.js 20+ |\n\n---\n\n## Example Interactions\n\n**\"How am I doing right now?\"**\n```bash\nnpx neuroskill status --json\n```\n→ Interpret scores naturally, mentioning focus, relaxation, mood, and any notable\n  ratios (FAA, TBR). Suggest an action only if metrics indicate a need.\n\n**\"I can't concentrate\"**\n```bash\nnpx neuroskill status --json\n```\n→ Check if metrics confirm it (high theta, low beta, rising TBR, high drowsiness).\n→ If confirmed, suggest an appropriate protocol from `references\u002Fprotocols.md`.\n→ If metrics look fine, the issue may be motivational rather than neurological.\n\n**\"Compare my focus today vs yesterday\"**\n```bash\nnpx neuroskill compare --json\n```\n→ Interpret trends, not just numbers. Mention what improved, what declined, and\n  possible causes.\n\n**\"When was I last in a flow state?\"**\n```bash\nnpx neuroskill search-labels \"flow\" --json\nnpx neuroskill search --json\n```\n→ Report timestamps, associated metrics, and what the user was doing (from labels).\n\n**\"How did I sleep?\"**\n```bash\nnpx neuroskill sleep --json\n```\n→ Report sleep architecture (N3%, REM%, efficiency), compare to healthy targets,\n  and note any issues (high wake epochs, low REM).\n\n**\"Mark this moment — I just had a breakthrough\"**\n```bash\nnpx neuroskill label \"breakthrough\"\n```\n→ Confirm label saved. Optionally note the current metrics to remember the state.\n\n---\n\n## References\n\n- [NeuroSkill Paper — arXiv:2603.03212](https:\u002F\u002Farxiv.org\u002Fabs\u002F2603.03212) (Kosmyna & Hauptmann, MIT Media Lab)\n- [NeuroSkill Desktop App](https:\u002F\u002Fgithub.com\u002FNeuroSkill-com\u002Fskill) (GPLv3)\n- [NeuroLoop CLI Companion](https:\u002F\u002Fgithub.com\u002FNeuroSkill-com\u002Fneuroloop) (GPLv3)\n- [MIT Media Lab Project](https:\u002F\u002Fwww.media.mit.edu\u002Fprojects\u002Fneuroskill\u002Foverview\u002F)\n",{"name":5,"author":24,"license":15,"version":25,"metadata":26,"platforms":38,"description":42},"Hermes Agent + Nous Research","1.0.0",{"hermes":27},{"tags":28,"category":31,"related_skills":37},[29,30,31,32,33,34,35,36],"BCI","neurofeedback","health","focus","EEG","cognitive-state","biometrics","neuroskill",[],[39,40,41],"linux","macos","windows","Connect to a running NeuroSkill instance and incorporate the user's real-time cognitive and emotional state (focus, relaxation, mood, cognitive load, drowsiness, heart rate, HRV, sleep staging, and 40+ derived EXG scores) into responses. Requires a BCI wearable (Muse 2\u002FS or OpenBCI) and the NeuroSkill desktop app running locally.\n","main","cd5116e81009ad620d09c7bc8664ce8c37f88a99","02 Business\u002F05 Health & Fitness\u002Fneuroskill-bci",0,"https:\u002F\u002Fgithub.com\u002Fvdcworkshop\u002FSkills-Catalog","https:\u002F\u002Fgithub.com\u002Fvdcworkshop","https:\u002F\u002Fvdcworkshop.com","2026-06-28 03:22:57",{"source":8,"skillName":5,"commands":52,"prompt":62,"zipAvailable":63},[53,56,59],{"tool":54,"command":55},"npx","npx skills add vdcworkshop\u002FSkills-Catalog --skill neuroskill-bci",{"tool":57,"command":58},"bunx","bunx skills add vdcworkshop\u002FSkills-Catalog --skill neuroskill-bci",{"tool":60,"command":61},"pnpm","pnpm dlx skills add vdcworkshop\u002FSkills-Catalog --skill neuroskill-bci","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fvdcworkshop\u002FSkills-Catalog\u002Fblob\u002Fmain\u002F02 Business\u002F05 Health & Fitness\u002Fneuroskill-bci\u002FSKILL.md",true,[65,71,75,79],{"path":66,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":69,"sourceHtmlUrl":70},"README.md","REFERENCE","参考文档",990,"https:\u002F\u002Fgithub.com\u002Fvdcworkshop\u002FSkills-Catalog\u002Fblob\u002Fmain\u002F02 Business\u002F05 Health & Fitness\u002Fneuroskill-bci\u002FREADME.md",{"path":72,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":73,"sourceHtmlUrl":74},"references\u002Fapi.md",8386,"https:\u002F\u002Fgithub.com\u002Fvdcworkshop\u002FSkills-Catalog\u002Fblob\u002Fmain\u002F02 Business\u002F05 Health & Fitness\u002Fneuroskill-bci\u002Freferences\u002Fapi.md",{"path":76,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":77,"sourceHtmlUrl":78},"references\u002Fmetrics.md",9479,"https:\u002F\u002Fgithub.com\u002Fvdcworkshop\u002FSkills-Catalog\u002Fblob\u002Fmain\u002F02 Business\u002F05 Health & Fitness\u002Fneuroskill-bci\u002Freferences\u002Fmetrics.md",{"path":80,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":81,"sourceHtmlUrl":82},"references\u002Fprotocols.md",16532,"https:\u002F\u002Fgithub.com\u002Fvdcworkshop\u002FSkills-Catalog\u002Fblob\u002Fmain\u002F02 Business\u002F05 Health & Fitness\u002Fneuroskill-bci\u002Freferences\u002Fprotocols.md",[84,91,98,106,113,120],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":19},"01M77XBV88FMNX83MKDZMXKQZ2","rhaios-staging","Interact with the Rhaios staging REST API for yield operations. Discover -> prepare -> setup-if-needed -> sign -> execute flow with pluggable signer backend. Triggers on requests involving DeFi yield, vault deposits, redeems, rebalancing, or Rhaios API.","https:\u002F\u002Fgithub.com\u002Fvdcworkshop\u002FSkills-Catalog\u002Fblob\u002Fmain\u002F12 Blockchain\u002F03 DeFi\u002Frhaios-staging\u002FSKILL.md",[],[],{"skillNo":92,"name":93,"nameZh":6,"description":94,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":95,"categories":96,"keywords":97,"publishedAt":19},"01M77X7AFQGDCFHC25GQ7V92GZ","git-commit-push","Commit and push repository changes safely. Use when user asks to commit, push, or verify and push current changes.","https:\u002F\u002Fgithub.com\u002Fvdcworkshop\u002FSkills-Catalog\u002Fblob\u002Fmain\u002F12 Blockchain\u002F01 Smart Contracts\u002Fgit-commit-push\u002FSKILL.md",[],[],{"skillNo":99,"name":100,"nameZh":6,"description":101,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":102,"licenseFileUrl":6,"sourceHtmlUrl":103,"categories":104,"keywords":105,"publishedAt":19},"01M77X71FJ1KR7PTBPRC7S2241","exec-slurm-compile","Compile TensorRT-LLM on a SLURM cluster. Covers submitting a batch job with a container image, monitoring the job, and verifying the build. Use when the user wants to compile TRT-LLM remotely via SLURM rather than on a local compute node.","Apache-2.0","https:\u002F\u002Fgithub.com\u002Fvdcworkshop\u002FSkills-Catalog\u002Fblob\u002Fmain\u002F12 Blockchain\u002F01 Smart Contracts\u002Fexec-slurm-compile\u002FSKILL.md",[],[],{"skillNo":107,"name":108,"nameZh":6,"description":109,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":110,"categories":111,"keywords":112,"publishedAt":19},"01M77X4BQJ025SPPGRQ96X72QV","databases","Work with MongoDB (document database, BSON documents, aggregation pipelines, Atlas cloud) and PostgreSQL (relational database, SQL queries, psql CLI, pgAdmin). Use when designing database schemas, writing queries and aggregations, optimizing indexes for performance, performing database migrations, configuring replication and sharding, implementing backup and restore strategies, managing database users and permissions, analyzing query performance, or administering production databases.","https:\u002F\u002Fgithub.com\u002Fvdcworkshop\u002FSkills-Catalog\u002Fblob\u002Fmain\u002F11 Databases\u002F03 NoSQL Databases\u002Fdatabases\u002FSKILL.md",[],[],{"skillNo":114,"name":115,"nameZh":6,"description":116,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":117,"categories":118,"keywords":119,"publishedAt":19},"01M77WZYZGCV9DK5HA0XCWSK97","toast","Toast — restaurant POS, orders, menus, employees, revenue centers, and reporting.","https:\u002F\u002Fgithub.com\u002Fvdcworkshop\u002FSkills-Catalog\u002Fblob\u002Fmain\u002F10 Lifestyle\u002F06 Culinary Arts\u002Ftoast\u002FSKILL.md",[],[],{"skillNo":121,"name":122,"nameZh":6,"description":123,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":124,"categories":125,"keywords":126,"publishedAt":19},"01M77WYYESVCXT81ERPHM77SA9","k-schoollunch-menu","Use when the user asks for Korean school meal menus (급식 식단) by natural-language education office and school name, via k-skill-proxy NEIS school-search and school-meal routes.","https:\u002F\u002Fgithub.com\u002Fvdcworkshop\u002FSkills-Catalog\u002Fblob\u002Fmain\u002F10 Lifestyle\u002F06 Culinary Arts\u002Fk-schoollunch-menu\u002FSKILL.md",[],[]]