[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7BFXM3Z1C08VB8EVEF3B9C5":3,"skill-same:01M7BFXM3Z1C08VB8EVEF3B9C5":77},{"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":42,"commitSha":43,"skillDirectory":44,"forksCount":45,"repositoryHtmlUrl":46,"repositoryHomepageUrl":6,"ownerHtmlUrl":47,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":48,"install":49,"resources":62},"01M7BFXM3Z1C08VB8EVEF3B9C5","neuroskill-bci",null,"Use live BCI cognitive and mood state from NeuroSkill.","LIJALEN23\u002FBeryl","LIJALEN23","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F141412346?v=4","01M7AQK5G18E0M3NKP1S35F4KE","oneplusnine","01M7AQK5GNQE3MMPFJ9TCCJQCN",1,"MIT","https:\u002F\u002Fgithub.com\u002FLIJALEN23\u002FBeryl\u002Fblob\u002Fmaster\u002Flocal-agent\u002Foptional-skills\u002Fhealth\u002Fneuroskill-bci\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: neuroskill-bci\ndescription: \"Use live BCI cognitive and mood state from NeuroSkill.\"\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":7},"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","master","4a5caebee4b5f9068d3a68c9a7ecd8df12bd4962","local-agent\u002Foptional-skills\u002Fhealth\u002Fneuroskill-bci",0,"https:\u002F\u002Fgithub.com\u002FLIJALEN23\u002FBeryl","https:\u002F\u002Fgithub.com\u002FLIJALEN23","2026-09-01 14:02:08",{"source":8,"skillName":5,"commands":50,"prompt":60,"zipAvailable":61},[51,54,57],{"tool":52,"command":53},"npx","npx skills add LIJALEN23\u002FBeryl --skill neuroskill-bci",{"tool":55,"command":56},"bunx","bunx skills add LIJALEN23\u002FBeryl --skill neuroskill-bci",{"tool":58,"command":59},"pnpm","pnpm dlx skills add LIJALEN23\u002FBeryl --skill neuroskill-bci","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FLIJALEN23\u002FBeryl\u002Fblob\u002Fmaster\u002Flocal-agent\u002Foptional-skills\u002Fhealth\u002Fneuroskill-bci\u002FSKILL.md",true,[63,69,73],{"path":64,"resourceType":65,"resourceTypeDesc":66,"sizeBytes":67,"sourceHtmlUrl":68},"references\u002Fapi.md","REFERENCE","参考文档",8386,"https:\u002F\u002Fgithub.com\u002FLIJALEN23\u002FBeryl\u002Fblob\u002Fmaster\u002Flocal-agent\u002Foptional-skills\u002Fhealth\u002Fneuroskill-bci\u002Freferences\u002Fapi.md",{"path":70,"resourceType":65,"resourceTypeDesc":66,"sizeBytes":71,"sourceHtmlUrl":72},"references\u002Fmetrics.md",9479,"https:\u002F\u002Fgithub.com\u002FLIJALEN23\u002FBeryl\u002Fblob\u002Fmaster\u002Flocal-agent\u002Foptional-skills\u002Fhealth\u002Fneuroskill-bci\u002Freferences\u002Fmetrics.md",{"path":74,"resourceType":65,"resourceTypeDesc":66,"sizeBytes":75,"sourceHtmlUrl":76},"references\u002Fprotocols.md",16532,"https:\u002F\u002Fgithub.com\u002FLIJALEN23\u002FBeryl\u002Fblob\u002Fmaster\u002Flocal-agent\u002Foptional-skills\u002Fhealth\u002Fneuroskill-bci\u002Freferences\u002Fprotocols.md",[78,85,92,99,106,113],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":19},"01M7BGCRH58RARQTF3R8CZ84DB","test-driven-development","TDD: enforce RED-GREEN-REFACTOR, tests before code.","https:\u002F\u002Fgithub.com\u002FLIJALEN23\u002FBeryl\u002Fblob\u002Fmaster\u002Flocal-agent\u002Fskills\u002Fsoftware-development\u002Ftest-driven-development\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":19},"01M7BGCK0GGNV3K6NWMM0MDN3W","systematic-debugging","4-phase root cause debugging: understand bugs before fixing.","https:\u002F\u002Fgithub.com\u002FLIJALEN23\u002FBeryl\u002Fblob\u002Fmaster\u002Flocal-agent\u002Fskills\u002Fsoftware-development\u002Fsystematic-debugging\u002FSKILL.md",[],[],{"skillNo":93,"name":94,"nameZh":6,"description":95,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":96,"categories":97,"keywords":98,"publishedAt":19},"01M7BGCF0TAZPKSM4WMYA27XGD","spike","Throwaway experiments to validate an idea before build.","https:\u002F\u002Fgithub.com\u002FLIJALEN23\u002FBeryl\u002Fblob\u002Fmaster\u002Flocal-agent\u002Fskills\u002Fsoftware-development\u002Fspike\u002FSKILL.md",[],[],{"skillNo":100,"name":101,"nameZh":6,"description":102,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":103,"categories":104,"keywords":105,"publishedAt":19},"01M7BGCBH01YYYBQWR7ZFRMX27","simplify-code","Parallel 4-agent cleanup of recent code changes.","https:\u002F\u002Fgithub.com\u002FLIJALEN23\u002FBeryl\u002Fblob\u002Fmaster\u002Flocal-agent\u002Fskills\u002Fsoftware-development\u002Fsimplify-code\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},"01M7BGC8MGHS5SRJ3NZYYNAKJY","requesting-code-review","Pre-commit review: security scan, quality gates, auto-fix.","https:\u002F\u002Fgithub.com\u002FLIJALEN23\u002FBeryl\u002Fblob\u002Fmaster\u002Flocal-agent\u002Fskills\u002Fsoftware-development\u002Frequesting-code-review\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},"01M7BGC4HB5ZJP5N19MZTZXKZ1","python-debugpy","Debug Python: pdb REPL + debugpy remote (DAP).","https:\u002F\u002Fgithub.com\u002FLIJALEN23\u002FBeryl\u002Fblob\u002Fmaster\u002Flocal-agent\u002Fskills\u002Fsoftware-development\u002Fpython-debugpy\u002FSKILL.md",[],[]]