Overview

NeuroSkill (MIT Media Lab, arXiv:2603.03212) is an open-source desktop application that streams, processes, and embeds EEG data from consumer Brain-Computer Interface wearables (Muse, OpenBCI, AttentivU) in real-time, fully offline. It exposes a local WebSocket API with commands like status, search, compare, sleep, and sessions that return structured neuroscientific metrics: focus, relaxation, engagement, cognitive load, drowsiness, heart rate, HRV, sleep staging, and 30+ derived scores.

This skill enables Hermes Agent to connect to a running NeuroSkill instance and incorporate the user's real-time cognitive/emotional state into its responses. A user wearing a Muse headband while coding could have an agent that notices their focus dropping and suggests a break, detects stress spikes and adjusts its communication style, or tracks cognitive load to decide when to give detailed explanations vs. concise answers.

This is niche — it requires BCI hardware (~$250 Muse headband) and the NeuroSkill desktop app running. But for users in the BCI/neurofeedback space, it's a genuinely novel integration.

Replaces the relevant portion of #500 (closed as over-scoped).

How It Works

NeuroSkill's Local API

NeuroSkill runs a WebSocket server on localhost (mDNS _skill._tcp), discoverable via lsof. Key commands:

Also available via CLI: npx neuroskill <command> (requires Node.js 20+).

Skill Behavior

The skill would instruct Hermes to:

1. Check NeuroSkill status at session start via npx neuroskill status or WebSocket
2. Inject EXG state summary into context when relevant (user asks about their state, or signals suggest it's useful)
3. Interpret metrics naturally — translate raw numbers into felt qualities ("your focus has been declining over the past hour" rather than "beta/alpha ratio dropped from 1.8 to 1.2")
4. Use search/compare when the user asks about trends, historical states, or wants to compare sessions
5. Auto-label notable moments when the user reports insights, breakthroughs, or significant states
6. Suggest protocols — breathing exercises, focus techniques, break reminders based on detected state (NeuroSkill includes 70+ guided protocols)

Example Interactions

User: "How am I doing right now?"
Agent: [runs npx neuroskill status]
Agent: "Your focus is solid right now — you've been in a good flow state 
        for about 20 minutes. Heart rate is steady. Your alpha activity is 
        elevated which usually means relaxed concentration. Good time to 
        tackle something complex."

User: "Compare my focus today vs yesterday"
Agent: [runs npx neuroskill compare]
Agent: "Yesterday you had two strong focus blocks (10am and 2pm). Today 
        you've had one starting around 11am that's still going. Your 
        overall engagement is higher today but you've had more stress 
        spikes — probably that deployment issue earlier."

User: "I can't concentrate"
Agent: [checks status, sees high theta/alpha ratio + low engagement]
Agent: "Your brainwaves confirm it — theta is dominant right now, which 
        usually means mental fatigue. Want me to guide you through a 
        2-minute box breathing exercise? It typically resets focus within 
        5-10 minutes."

Implementation

Classification

This should be a Skill (not a tool) because:

• It wraps an external CLI (npx neuroskill) that the agent calls via terminal
• It can be expressed entirely as instructions + shell commands + existing tools
• No custom Python integration needed — just parse CLI/JSON output
• Niche audience — should NOT be bundled; belongs on the Skills Hub

Skill Structure

skills/health/neuroskill-bci/
  SKILL.md           — Main skill with connection, commands, interpretation guidance
  references/
    metrics.md       — EXG metric definitions and interpretation guide
    protocols.md     — Available guided protocols and when to suggest them

Prerequisites

• Node.js 20+ installed
• NeuroSkill desktop app running with a connected BCI device
• npx neuroskill status returns data

Dependencies on Other Issues

• Feature: Implicit Signal Detection & Behavioral Nudges — Detect User State from Text and Adjust Agent Behavior (inspired by NeuroSkill) #692 (Signal Detection): If implemented, the signal detector could trigger NeuroSkill data fetches when health/focus/stress signals fire in user text, making the integration more proactive
• Works standalone without Feature: Implicit Signal Detection & Behavioral Nudges — Detect User State from Text and Adjust Agent Behavior (inspired by NeuroSkill) #692

Total Effort

~200-300 lines of SKILL.md + references. Skill only, no code changes to core.

Pros & Cons

Pros

• First agent with BCI integration — No other general-purpose AI agent connects to brain-computer interfaces
• Zero core code changes — Pure skill, uses existing terminal tool
• Real utility for BCI users — Neurofeedback community is growing; Muse alone has sold millions of units
• Open source ecosystem — NeuroSkill is GPLv3 with active development from MIT Media Lab

Cons

• Extremely niche — Requires specific hardware + software. Very small user base.
• Hardware reliability — BCI signals are noisy; electrode placement, movement artifacts, and device battery affect data quality
• NeuroSkill dependency — If NeuroSkill project goes unmaintained, skill becomes useless
• GPLv3 concern — NeuroSkill is GPLv3 but the skill just calls its CLI (no code linking), so no license conflict

References

• NeuroSkill Paper — arXiv:2603.03212 (Kosmyna & Hauptmann, MIT Media Lab, March 2026)
• NeuroSkill App — github.com/NeuroSkill-com/skill (GPLv3)
• NeuroLoop Harness — github.com/NeuroSkill-com/neuroloop (GPLv3, reference for how to use the API)
• MIT Media Lab Project Page
• DAIR.AI Academy — Source of the research tip
• Hermes Agent Feature: Implicit Signal Detection & Behavioral Nudges — Detect User State from Text and Adjust Agent Behavior (inspired by NeuroSkill) #692 — Signal Detection (complementary)
• Supersedes relevant portion of Feature: Proactive Agent Context Loop — Signal-Driven Context Injection & Adaptive Engagement (inspired by NeuroSkill) #500 (closed)