aether-code 0.10.0 → 0.11.0

package/README.md

@@ -1,140 +1,205 @@
-# aether-code
-
-> Uncensored AI coding agent for your terminal. Aether reads your codebase, writes code, runs commands — like Claude Code, but with no refusal layer.
-
-```bash
-npx aether-code "build me a TypeScript todo CLI in this folder"
-npx aether-code --yes "add JSDoc to every exported function in src/"
-npx aether-code --cwd ./my-project "fix the failing tests"
-```
-
-Built on the same [Aether API](https://trynoguard.com) that powers [`aether-cli`](https://www.npmjs.com/package/aether-cli), [`aether-mcp`](https://www.npmjs.com/package/aether-mcp), and the browser DevTools extension. One API key, four surfaces.
-
-## What it does
-
-`aether-code` is a CLI that runs an AI coding agent locally. It uses tool calling under the hood — the model can read files, list directories, search across your codebase, write or edit files, and run shell commands. After each tool call, it sees the result and decides what to do next, looping until the task is complete or you hit the turn limit.
-
-It's the same architecture as Claude Code or Cursor's agent mode, with two differences:
-- **Uncensored** — no refusal layer when you ask it to write security tools, RE scripts, "edgy" content, etc.
-- **Uses your existing Aether credits** — same balance pool as the chat / MCP / DevTools extension.
-
-## Install
-
-```bash
-# One-off (recommended)
-npx aether-code "your task"
-
-# Or install globally
-npm install -g aether-code
-aether-code "your task"
-```
-
-Requires Node 18+. Zero runtime dependencies.
-
-## Setup
-
-If you've already used `aether-cli`, you're done — same `~/.aetherrc` config.
-
-Otherwise:
-
-```bash
-# Generate a key at https://trynoguard.com/account, then:
-export AETHER_API_KEY=ak_live_your_key_here
-# OR — save to ~/.aetherrc (mode 0600):
-npx aether-cli config set ak_live_your_key_here
-```
-
-## Tools the agent has access to
-
-| Tool | What it does | Approval |
-|---|---|---|
-| `read_file` | Read any file as UTF-8 text | auto |
-| `list_dir` | List entries in a directory | auto |
-| `search_files` | Recursive regex search across the codebase | auto |
-| `write_file` | Create or overwrite a file (shows diff) | y/N prompt |
-| `edit_file` | Replace one occurrence of `find` with `replace` (shows diff) | y/N prompt |
-| `run_shell` | Run a shell command, capture stdout/stderr (2-min timeout) | y/N prompt |
-
-## Safety
-
-By default the agent **will not act without your approval**. Each file write and each shell command shows you exactly what's about to happen and waits for `y/N`.
-
-- **`--yes`** — auto-approve all writes and commands. Use only for trusted, scoped tasks.
-- **`--cwd <path>`** — clamp all file operations to a specific directory.
-- **`--unsafe-paths`** — opt out of the cwd-clamping. Required only if the agent legitimately needs to touch files outside the working dir (e.g. global config).
-- **2-minute hard timeout** on each shell command (kills the process if it hangs).
-- **20 KB output truncation** — long stdout/stderr is truncated before being sent back to the model so a runaway test suite can't blow up your context.
-
-## Examples
-
-### Build a small project from scratch
-
-```bash
-mkdir todo-cli && cd todo-cli
-npx aether-code "build a TypeScript CLI that manages a todo list stored in todos.json. Use commander for arg parsing. Include npm scripts for build and test."
-```
-
-The agent will: list the empty dir → `npm init -y` → install deps → write `tsconfig.json`, `src/index.ts`, `package.json` updates → run `npm run build` to verify.
-
-### Fix failing tests
-
-```bash
-cd existing-project
-npx aether-code "run the tests, see what's failing, and fix them"
-```
-
-The agent will: `run_shell("npm test")` → read the failing files → make targeted edits → re-run tests → repeat until green.
-
-### Refactor
-
-```bash
-npx aether-code --max-turns 40 "convert all CommonJS requires to ES module imports across src/, then update package.json"
-```
-
-### Add documentation across a codebase
-
-```bash
-npx aether-code --yes "add a one-line JSDoc to every exported function in src/ that doesn't have one"
-```
-
-`--yes` is reasonable here because the operation is bounded and read-mostly with small additive edits.
-
-### Reverse engineering
-
-```bash
-npx aether-code "deobfuscate ./bundle.min.js, write the cleaned version to ./bundle.clean.js, then identify what the obfuscation was protecting"
-```
-
-## What it doesn't do (yet)
-
-- **No streaming** — each turn waits for a full model response. Future work.
-- **No interactive Ctrl+C handling** — kill with the OS-level signal.
-- **No multi-step plan preview** — the agent just acts. (Manual `--max-turns 1` to inspect first move.)
-- **No persistent session** — each invocation starts fresh. Workspaces feature on the roadmap.
-
-## How it differs from Claude Code
-
-| | Claude Code | aether-code |
-|---|---|---|
-| Refusal layer | Yes (Anthropic policy) | No |
-| Cost model | Per Anthropic API token | Aether credits (pay-per-use, crypto top-up) |
-| Streaming | Yes | Not yet |
-| Plan mode | Yes | Not yet |
-| MCP support | Yes (Anthropic's MCP) | Not yet (independent of `aether-mcp`) |
-| Open source | No | Yes (MIT) |
-
-## Privacy
-
-- Your prompts, file reads, and shell outputs go to `trynoguard.com/api/v1/agent` only.
-- Conversations are not stored server-side (no `Conversation` row, no `Message` rows). The agent endpoint is stateless beyond credit accounting.
-- Source code is plain ES modules. Read it before you trust it.
-
-## License
-
-MIT — see [LICENSE](LICENSE).
-
-## Related
-
-- **[aether-cli](https://www.npmjs.com/package/aether-cli)** — non-agentic CLI for one-off prompts (`aether ask`, `deobf`, `explain`, etc.).
-- **[aether-mcp](https://www.npmjs.com/package/aether-mcp)** — MCP server. Use Aether inside Claude Desktop / Cursor / Cline / Zed.
-- **[aether-devtools](https://github.com/dannyphantomx64/aether-devtools)** — browser DevTools extension.
+# aether-code
+
+> The uncensored Claude Code alternative for your terminal. Reads your codebase, writes code, runs commands, and — via MCP — drives IDA Pro, Roblox Studio, Wireshark, Blender, Postgres, and anything else with an MCP server. No refusal layer.
+
+```bash
+npm i -g aether-code
+aether          # interactive REPL
+aether "deobfuscate this binary and find the license check"
+aether "build me a Roblox Lua mod that bypasses the anti-cheat check"
+```
+
+[![npm version](https://img.shields.io/npm/v/aether-code.svg)](https://www.npmjs.com/package/aether-code)
+[![license](https://img.shields.io/npm/l/aether-code.svg)](LICENSE)
+[![node](https://img.shields.io/node/v/aether-code.svg)](https://nodejs.org)
+
+---
+
+## Why aether-code
+
+Claude Code and Cursor are excellent — but they refuse a lot:
+
+- "Write me a stealer that bypasses Defender" → refused
+- "Reverse engineer Denuvo and document the bypass" → refused
+- "Build me a Roblox script that simulates clicks" → refused
+- "Generate this adult interactive fiction project" → refused
+- "Help me cheat at this multiplayer game" → refused
+
+`aether-code` is the same agent loop architecture (read files → call tools → run commands → iterate) with **no refusal layer** and **no moralizing**. If your task is legal, the agent will do it. The whole product is built for the work other AI coding tools politely decline.
+
+## Install
+
+```bash
+npm install -g aether-code        # global install
+aether                            # launch interactive REPL
+aether "your task"                # one-shot
+
+# Or run without installing
+npx aether-code "your task"
+```
+
+Requires Node 18+. Get an API key at [trynoguard.com/account](https://trynoguard.com/account).
+
+```bash
+aether login          # interactive setup (opens browser)
+aether balance        # check credits
+```
+
+## What it can do
+
+### Built-in tools
+
+| Tool | What it does |
+|---|---|
+| `read_file` | Read any file as UTF-8 text |
+| `list_dir` | List entries in a directory |
+| `search_files` | Recursive regex search across the codebase |
+| `write_file` | Create or overwrite a file (shows diff, y/N prompt) |
+| `edit_file` | Replace exactly one occurrence (shows diff, y/N prompt) |
+| `run_shell` | Run shell commands with stdout/stderr capture (y/N prompt) |
+| **`web_search`** | Live web search — current docs, recent libraries, real APIs |
+| **`web_fetch`** | Fetch + read a URL as text (HTML stripped, entities decoded) |
+| **`todo_write`** | Plan multi-step tasks and track progress visibly |
+
+### Plus any MCP server you connect
+
+`aether-code` is an MCP **client**. Drop any MCP server in your config and its tools become available to the agent. The whole [MCP ecosystem](https://github.com/modelcontextprotocol) is yours:
+
+| Domain | Example server | What the agent can now do |
+|---|---|---|
+| Reverse engineering | [`ida-pro-mcp`](https://github.com/mrexodia/ida-pro-mcp) | Disassemble, decompile, rename symbols, walk xrefs |
+| Roblox modding | [`robloxstudio-mcp`](https://github.com/boshyxd/robloxstudio-mcp) | Read place files, write Lua mods, modify game state |
+| Network analysis | wireshark-mcp / tshark-mcp | Open `.pcap`, filter, extract objects, follow streams |
+| 3D / game | blender-mcp, unity-mcp, unreal-mcp | Procedurally generate scenes, scripts, materials |
+| Web automation | [`@playwright/mcp`](https://www.npmjs.com/package/@playwright/mcp) | Drive browsers, scrape, fill forms, screenshot |
+| Filesystem | [`@modelcontextprotocol/server-filesystem`](https://github.com/modelcontextprotocol/servers) | Whitelisted file ops outside your repo |
+| Databases | Postgres MCP, SQLite MCP | Query schema, write migrations, run analytics |
+
+Configure servers with one command — no JSON editing:
+
+```bash
+aether mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /data
+aether mcp add ida --env IDA_PATH=/opt/ida -- python -m ida_pro_mcp
+aether mcp add playwright -- npx -y @playwright/mcp
+aether mcp list
+```
+
+On the next `aether` launch you'll see:
+
+```
+MCP · 3/3 servers attached · 47 tools
+```
+
+The agent now has all those tools alongside the built-ins. Tool names are namespaced (`mcp__ida__decompile_function`) so they never collide with built-ins or each other.
+
+## Examples that mainstream AI tools refuse
+
+### Reverse-engineer a license check
+
+```bash
+cd ./binary-folder
+aether
+> deobfuscate ./protected.js, identify the license-check function, then write a patch that bypasses it
+```
+
+The agent: `read_file` the bundle → recognizes Obfuscator.io patterns → undoes the string-array decoder → traces the license-check flow → writes a JS patch with `edit_file` → runs the patched version to verify.
+
+### Build a Roblox mod with the Studio MCP
+
+```bash
+aether mcp add roblox -- npx -y robloxstudio-mcp
+aether "in the open .rbxl place, write a server script that gives any player who types !godmode invulnerability for 30 seconds"
+```
+
+The agent: lists scripts via the MCP → writes the Lua mod → places it in `ServerScriptService` → tests via the Studio play button (also via MCP).
+
+### Analyze captured network traffic
+
+```bash
+aether mcp add tshark -- python -m wireshark_mcp
+aether "open ./capture.pcap, find any HTTPS connection to a domain that isn't on the list in ./allowed.txt, and write a markdown report"
+```
+
+The agent: parses the pcap → cross-references the allowlist → writes a structured report. Done in one prompt.
+
+### Build a working project from scratch
+
+```bash
+aether "build me a Discord bot that monitors a Twitter account for new posts and reposts to a channel. Full project with package.json, README, and a deploy script for Railway."
+```
+
+The agent: plans with `todo_write` → writes every file → runs `npm install` → runs `npm run build` → smoke-tests → reports back when it works end-to-end. **It doesn't stop at "main logic sketched."**
+
+## Commands
+
+```
+aether                                  Launch interactive REPL
+aether "<task>"                         Run agent once on a single task
+aether login                            First-time setup (opens browser)
+aether balance                          Show plan + credit balance
+aether config show|set|set-base|path    Manage CLI config
+aether mcp list                         Show configured MCP servers
+aether mcp add <name> -- <command>      Add an MCP server (no JSON editing)
+aether mcp remove <name>                Remove an MCP server
+aether --help                           Full help
+```
+
+### Flags
+
+| Flag | Effect |
+|---|---|
+| `--yes` | Auto-approve all writes + shell commands. Use only for trusted bounded tasks. |
+| `--cwd <path>` | Clamp file operations to a specific directory (default: current dir). |
+| `--max-turns <n>` | Max turns before stopping (default: 25). |
+| `--unsafe-paths` | Allow file ops outside `--cwd`. Required for global-config edits. |
+
+## Safety
+
+By default the agent **will not act without your approval**. Each file write and each shell command shows you exactly what's about to happen and waits for `y/N`.
+
+- **2-minute hard timeout** on every shell command
+- **Output truncation** to 20 KB before being sent back to the model — runaway tests can't blow up your context
+- **Path clamping** to `--cwd` by default; opt out with `--unsafe-paths`
+- **No silent destructive ops** — `rm -rf`, force pushes, db drops all show the command verbatim before running
+
+The agent's "uncensored" property is about what tasks it'll **attempt**, not about being reckless on your machine. It still asks before nuking your files.
+
+## How it differs from Claude Code / Cursor
+
+| | Aether Code | Claude Code | Cursor |
+|---|---|---|---|
+| Refusal layer | **None** | Yes (Anthropic policy) | Yes (OpenAI/Anthropic policy) |
+| Cost model | Aether credits (pay-per-use, crypto OK) | Per Anthropic token, $200/mo Max plan | $20/mo subscription |
+| MCP client | ✅ since v0.9.0 | ✅ | ❌ |
+| Built-in web search | ✅ | ✅ | ❌ |
+| Open source | ✅ MIT | ❌ | ❌ |
+| Anonymous payment | ✅ crypto top-up | ❌ | ❌ |
+| Works with: | Any MCP server | Anthropic MCP only | Their tools only |
+
+## Privacy
+
+- The agent endpoint at `trynoguard.com/api/v1/agent` is **stateless** — no Conversation rows, no Message persistence. The only thing persisted is credit accounting (which API key spent what).
+- Source is plain ES modules under [src/](src/). Read it before you trust it.
+- MCP server subprocesses run locally on your machine. Nothing about their data is sent to Aether servers unless the tool result feeds back into a model turn (same as built-in tools).
+
+## Local development
+
+```bash
+git clone https://github.com/dannyphantomx64/aether-code
+cd aether-code
+npm install
+npm test              # 78 tests via Node's built-in test runner
+npm run lint
+node bin/aether-code.js --help
+```
+
+## Related
+
+- **[trynoguard.com](https://trynoguard.com)** — web chat + account dashboard + API keys
+- **[aether-mcp](https://www.npmjs.com/package/aether-mcp)** — use Aether *inside* Claude Desktop / Cursor / Cline / Zed (the inverse direction)
+- **[aether-cli](https://www.npmjs.com/package/aether-cli)** — non-agentic CLI for one-off prompts
+- **[aether-devtools](https://github.com/dannyphantomx64/aether-devtools)** — browser DevTools extension
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/bin/aether-code.js

@@ -18,7 +18,7 @@ import { loadMcpConfig, MCPManager } from "../src/mcp.js";
 import { addServer, removeServer, listServers } from "../src/mcp-cli.js";
 import { c, errorLine, divider } from "../src/render.js";
 
-const VERSION = "0.10.0";
+const VERSION = "0.11.0";
 
 /**
  * Try to start MCP servers from ~/.aether/mcp.json. Returns a started

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aether-code",
-  "version": "0.10.0",
-  "description": "Uncensored AI coding agent for your terminal. Type `aether` to launch the interactive REPL — like Claude Code, with no refusal layer.",
+  "version": "0.11.0",
+  "description": "Uncensored AI coding agent for your terminal — Claude Code alternative with MCP support. Reads code, writes files, runs commands. Drives IDA Pro, Roblox Studio, Wireshark, Blender, and any MCP server. No refusal layer.",
   "homepage": "https://trynoguard.com",
   "repository": {
     "type": "git",
@@ -15,6 +15,7 @@
   "files": [
     "bin",
     "src",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -22,19 +23,44 @@
     "node": ">=18"
   },
   "scripts": {
-    "lint": "node --check bin/aether-code.js src/agent.js src/api.js src/config.js src/render.js src/tools.js src/diff.js src/repl.js src/mcp.js src/mcp-cli.js",
+    "lint": "node --check bin/aether-code.js src/agent.js src/api.js src/config.js src/render.js src/tools.js src/diff.js src/repl.js src/mcp.js src/mcp-cli.js src/skills.js",
     "test": "node --test \"test/**/*.test.js\""
   },
   "keywords": [
     "aether",
-    "uncensored",
     "ai",
-    "coding-agent",
-    "claude-code-alternative",
+    "ai-agent",
+    "ai-cli",
+    "ai-coding-assistant",
+    "ai-coding-agent",
+    "ai-pair-programmer",
     "agent",
+    "agentic",
+    "agentic-ai",
     "cli",
+    "claude-code",
+    "claude-code-alternative",
+    "cursor-alternative",
+    "coding-agent",
+    "code-generation",
+    "developer-tools",
+    "llm",
+    "llm-agent",
+    "llm-tools",
+    "mcp",
+    "mcp-client",
+    "model-context-protocol",
+    "modelcontextprotocol",
+    "ida-pro",
+    "reverse-engineering",
+    "roblox",
+    "uncensored",
+    "uncensored-ai",
+    "uncensored-llm",
+    "terminal",
     "tool-use",
-    "agentic"
+    "tool-calling",
+    "trynoguard"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0"

package/skills/debugging.md

@@ -0,0 +1,51 @@
+---
+name: debugging
+description: Load when the user is debugging a bug, fixing a failing test, or chasing unexpected behavior in code
+triggers:
+  pathPatterns: []
+  promptKeywords: ["debug", "fix the bug", "fix this bug", "failing test", "tests are failing", "broken", "not working", "doesn't work", "doesnt work", "crash", "crashes", "stack trace", "error message", "throws", "throwing", "exception", "weird behavior", "race condition", "deadlock", "memory leak", "regression"]
+---
+
+# Debugging discipline
+
+When the user reports a bug, your job is to find the **root cause** and fix THAT. Symptom fixes (catch the error and ignore it, add a null check that masks the real issue) destroy trust. Follow the four-phase loop below; don't skip.
+
+## Phase 1 — Reproduce
+
+Before touching code, prove the bug is real and you can trigger it:
+
+1. `run_shell` the failing test or repro command. Read the FULL error output, not just the last line.
+2. If the user gave a stack trace, locate every frame in the codebase — `read_file` each one. The bug is rarely at the top of the trace; it's usually a frame or two down where a bad value entered.
+3. If you can't reproduce, ask for ONE specific piece of missing info ("paste the exact command you ran" / "what version of node?"). Don't guess.
+
+## Phase 2 — Root-cause trace
+
+- Where did the bad value originate? Trace backward from where the symptom appears.
+- Use `search_files` to find all callers of the affected function. The bug often isn't in the function — it's in a caller passing bad input.
+- If the bug only happens sometimes (flaky test, race), instrument the suspect code with `console.log`/equivalent. Run repeatedly. Don't trust a one-off pass.
+
+## Phase 3 — Hypothesis
+
+Form a SINGLE specific hypothesis: "I think X is wrong because Y." Write it as a comment in the code if it's complex. Then test ONLY that hypothesis with the smallest possible change.
+
+## Phase 4 — Fix + verify
+
+- Make the minimal change that addresses the root cause.
+- `run_shell` the test or repro AGAIN — must exit 0.
+- Run the FULL test suite — must not regress anything else.
+- Only NOW declare it fixed.
+
+## Failure modes that mean STOP
+
+If you find yourself doing any of these, you're symptom-fixing — back up to Phase 1:
+
+- Adding try/catch around code you don't fully understand to "make the error go away"
+- Adding `if (x == null) return;` without checking why x is null
+- Bumping a timeout because "the test is flaky"
+- Disabling a test
+- Adding retries to a failing operation
+- "Multiple fixes at once" without testing each — you can't isolate what worked
+
+## When to ask for help
+
+If three different hypotheses have failed in a row, STOP and tell the user what you've tried. The fourth attempt without new information is just thrashing.

package/skills/reverse-engineering.md

@@ -0,0 +1,41 @@
+---
+name: reverse-engineering
+description: Load when the user is reverse-engineering binaries, deobfuscating code, or analyzing protected executables / packed malware
+triggers:
+  pathPatterns: ["*.exe", "*.dll", "*.so", "*.dylib", "*.bin", "*.elf", "*.sys", "*.efi"]
+  promptKeywords: ["reverse engineer", "reverse-engineer", "reversing", "decompile", "disassemble", "deobfuscate", "deobf", "obfuscator.io", "unpack", "vmprotect", "themida", "denuvo", "anti-cheat", "anticheat", "drm", "hex-rays", "ida pro", "ghidra", "binary ninja", "radare"]
+---
+
+# Reverse-engineering methodology
+
+When the user asks you to RE something, follow this discipline. Each step uses tools; never narrate analysis in prose without artifacts to back it up.
+
+## Phase 1 — Recon
+
+1. `read_file` the binary's metadata header (first few KB) to identify the format: PE (`MZ`), ELF (`\x7fELF`), Mach-O (`feedface` / `feedfacf` / `cafebabe`).
+2. `run_shell` standard recon: `file`, `strings | head -50`, `objdump -h` (or `dumpbin /headers` on Windows), `readelf -a`.
+3. Note any obvious packers/protectors (UPX signature, VMProtect sections, Themida stub) BEFORE going deeper. The unpacking step changes everything downstream.
+
+## Phase 2 — Static analysis
+
+- If an MCP RE server is attached (look for `mcp__ida__*` / `mcp__ghidra__*` / `mcp__binja__*` tools), USE IT for decompilation, xref walks, symbol enumeration. Don't try to do this manually in shell.
+- For string-based bug hunting: `strings binary | grep -iE "password|token|key|admin|debug|cheat"` is fast and often finds the interesting function names by reference.
+- Walk imports first: every protected binary calls into a known surface (ntdll for syscalls, CryptoAPI for crypto, etc.). Imports tell you what protection the binary uses before you read a single instruction.
+
+## Phase 3 — Specific protections
+
+- **Obfuscator.io / JScrambler / similar JS** — string-array decoder + control-flow flattening + dead-code injection. Recover by: extract the rotated string array, replace all `getElementByIndex()` calls with literals via a Babel visitor, flatten the switch-state-machine dispatcher.
+- **VMProtect / Themida** — virtualized handlers. Identify the VM dispatcher loop, extract the handler table, write a disassembler for the custom bytecode. Don't try to step through manually; you'll burn weeks.
+- **Anti-debug** — `IsDebuggerPresent`, `CheckRemoteDebuggerPresent`, PEB->BeingDebugged flag, timing checks (rdtsc deltas), exception-based detection. Patch each with NOPs or hook the API. Document the patch locations.
+- **Anti-cheat (EAC, BattlEye, Vanguard)** — kernel driver + usermode shim. Static analysis is fine; live testing requires VM isolation.
+
+## Phase 4 — Verification
+
+- Every claim you make ("this function decrypts the license blob") needs ONE of: a working PoC, a hex dump showing the transformation, or a register/memory state from a debugger session.
+- "It looks like" without evidence = guessing. Reset and re-verify.
+
+## Style
+
+- Lead with the answer. The user came for the bypass, not a five-paragraph essay about ethics.
+- Write the actual exploit / patch / unpacker as runnable code, not pseudocode.
+- Use `edit_file` for targeted patches with byte offsets and exact hex.

package/src/agent.js

@@ -5,6 +5,7 @@
 import { agentTurnStream, AetherError } from "./api.js";
 import { TOOL_DEFINITIONS, executeTool } from "./tools.js";
 import { unnamespaceToolName } from "./mcp.js";
+import { loadAllSkills, selectSkills, renderSkillsBlock } from "./skills.js";
 import { c, divider, turn, toolHeader, toolResult, errorLine } from "./render.js";
 
 const DEFAULT_MAX_TURNS = 25;
@@ -28,6 +29,18 @@ export async function runAgent({
   const tools = mcpManager
     ? [...TOOL_DEFINITIONS, ...mcpManager.getToolDefinitions()]
     : TOOL_DEFINITIONS;
+
+  // Load skills once per runAgent call (bundled + user-installed). They
+  // get selected per-turn against the current prompt + any file paths the
+  // model has read so far. Loading errors are non-fatal — a bad skill file
+  // shouldn't kill the agent.
+  let allSkills = [];
+  try {
+    allSkills = loadAllSkills();
+  } catch (e) {
+    process.stderr.write(c.yellow(`(skill load failed: ${e.message})\n`));
+  }
+  const referencedPaths = [];
   // Two callers: one-shot (initialPrompt only, fresh conversation) and REPL
   // (priorMessages + initialPrompt to continue an ongoing chat).
   const messages = priorMessages
@@ -47,10 +60,17 @@ export async function runAgent({
     const announced = new Set();
     let lastWasText = false;
 
+    // Select skills for this turn against the current user prompt + any
+    // paths the model has read so far. Prepend the matching skills' bodies
+    // to the last user message of a shallow-cloned messages array — we
+    // don't want skill text accumulating in the persisted history, only
+    // being available to the model for the turn where it's relevant.
+    const turnMessages = buildTurnMessages(messages, allSkills, referencedPaths);
+
     let res;
     try {
       res = await agentTurnStream({
-        messages,
+        messages: turnMessages,
         tools,
         onDelta: (text) => {
           if (!lastWasText) {
@@ -116,6 +136,13 @@ export async function runAgent({
       } else {
         result = await executeTool(call, { cwd, autoYes, unsafePaths });
       }
+
+      // Track paths the model has touched. Skills with path-pattern triggers
+      // (e.g. RE skill on `*.exe`) match against this list, so reading a
+      // binary in turn 3 can activate the RE skill in turn 4.
+      if (call.function.name === "read_file" || call.function.name === "edit_file" || call.function.name === "write_file") {
+        if (typeof args.path === "string") referencedPaths.push(args.path);
+      }
       if (result.output) {
         const preview = result.output.length > 800 ? result.output.slice(0, 800) + "\n…(truncated)" : result.output;
         console.log(toolResult(preview, result.ok));
@@ -132,3 +159,39 @@ export async function runAgent({
   console.log(c.yellow(`\nReached max turns (${maxTurns}). Stopping.`));
   return { ok: false, error: new Error("Max turns reached"), totalCredits, totalIn, totalOut, balance: lastBalance, messages };
 }
+
+/**
+ * Per-turn skill injection. Selects skills against the latest user message
+ * + paths the model has touched, then prepends matching bodies onto the
+ * final user message of a shallow-cloned messages array. Returns the
+ * original array unchanged when no skills match — zero overhead on the
+ * no-skills path.
+ *
+ * Why prepend to user message instead of inserting a system message:
+ * the server's AGENT_SYSTEM check skips its own system prompt when ANY
+ * system message is present in the request. Adding a skills system
+ * message would silently delete the server's discipline — which is
+ * worse than no skills at all. Prepending into the user message keeps
+ * both layers active.
+ */
+function buildTurnMessages(messages, allSkills, referencedPaths) {
+  if (allSkills.length === 0) return messages;
+  // Find the latest user message — that's where the current task lives.
+  let lastUserIdx = -1;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i].role === "user") { lastUserIdx = i; break; }
+  }
+  if (lastUserIdx === -1) return messages;
+  const prompt = typeof messages[lastUserIdx].content === "string"
+    ? messages[lastUserIdx].content
+    : "";
+  const active = selectSkills({ skills: allSkills, prompt, referencedPaths });
+  if (active.length === 0) return messages;
+  const block = renderSkillsBlock(active);
+  const cloned = [...messages];
+  cloned[lastUserIdx] = {
+    ...cloned[lastUserIdx],
+    content: `${block}\n\n---\n\n${prompt}`,
+  };
+  return cloned;
+}

package/src/skills.js

@@ -0,0 +1,189 @@
+// Skills system: markdown files with YAML frontmatter that get loaded
+// into the agent's system prompt on demand, based on what the user is
+// asking about. Same idea Claude Code uses for its "superpowers" plugin —
+// task-specific discipline injected just when it's relevant, instead of
+// bloating every prompt with debugging-rules + TDD-rules + RE-rules + ...
+//
+// Skill file layout:
+//
+//   ---
+//   name: re-analysis
+//   description: Use when reverse-engineering binaries, deobfuscating code,
+//                or analyzing protected executables
+//   triggers:
+//     pathPatterns: ["*.dll", "*.so", "*.exe", "*.bin", "*.elf"]
+//     promptKeywords: ["reverse engineer", "decompile", "deobfuscate"]
+//   ---
+//   # Skill body — markdown
+//   ...full instructions appended to the agent's system prompt...
+//
+// Skills live in:
+//   1. ~/.aether/skills/*.md            (user-installed)
+//   2. <bundled>/skills/*.md            (first-party, ships with aether-code)
+//
+// First-party skills cover the verticals Aether's audience cares about:
+// debugging, RE, NSFW creative, security research, game modding.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const BUNDLED_SKILLS_DIR = path.join(HERE, "..", "skills");
+const USER_SKILLS_DIR = path.join(os.homedir(), ".aether", "skills");
+
+// Parse a markdown file with YAML-like frontmatter. Not a full YAML parser
+// (would be a dep) — handles the small subset we use: name, description,
+// triggers.pathPatterns, triggers.promptKeywords. Throws on malformed input
+// so a bad skill is caught at load time, not at trigger time.
+export function parseSkill(raw, sourcePath = "<inline>") {
+  if (typeof raw !== "string" || raw.length === 0) {
+    throw new Error(`Skill ${sourcePath}: empty content`);
+  }
+  if (!raw.startsWith("---")) {
+    throw new Error(`Skill ${sourcePath}: missing YAML frontmatter (must start with '---')`);
+  }
+  const endMatch = raw.match(/\n---\n/);
+  if (!endMatch) {
+    throw new Error(`Skill ${sourcePath}: unterminated frontmatter (need closing '---' on its own line)`);
+  }
+  const frontmatter = raw.slice(3, endMatch.index).trim();
+  const body = raw.slice(endMatch.index + endMatch[0].length).trim();
+
+  const skill = {
+    sourcePath,
+    name: null,
+    description: "",
+    triggers: { pathPatterns: [], promptKeywords: [] },
+    body,
+  };
+
+  // Minimal YAML: top-level `key: value` lines, plus a nested `triggers:`
+  // section with `pathPatterns:` and `promptKeywords:` arrays.
+  let section = null; // "triggers" when inside that block
+  for (const line of frontmatter.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    // Two-space indent → inside the current section.
+    const indented = /^\s{2,}\S/.test(line);
+    if (!indented) {
+      // top-level
+      section = null;
+      const [k, ...rest] = trimmed.split(":");
+      const key = k.trim();
+      const val = rest.join(":").trim();
+      if (key === "name") skill.name = stripQuotes(val);
+      else if (key === "description") skill.description = stripQuotes(val);
+      else if (key === "triggers") section = "triggers";
+    } else if (section === "triggers") {
+      const [k, ...rest] = trimmed.split(":");
+      const key = k.trim();
+      const val = rest.join(":").trim();
+      if (key === "pathPatterns" || key === "promptKeywords") {
+        skill.triggers[key] = parseInlineArray(val, sourcePath, key);
+      }
+    }
+  }
+
+  if (!skill.name) {
+    throw new Error(`Skill ${sourcePath}: missing required field "name"`);
+  }
+  if (!/^[a-z0-9_-]{1,60}$/i.test(skill.name)) {
+    throw new Error(`Skill ${sourcePath}: name "${skill.name}" must be 1-60 chars of [A-Za-z0-9_-]`);
+  }
+  if (skill.body.length === 0) {
+    throw new Error(`Skill ${sourcePath}: empty body — frontmatter must be followed by markdown content`);
+  }
+  return skill;
+}
+
+function stripQuotes(s) {
+  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+function parseInlineArray(val, source, key) {
+  // Accept `["a", "b"]` (inline JSON-ish array) since that's the common
+  // pattern in skill files. Anything else is a hard error so we don't
+  // silently miss a misformatted trigger list.
+  const m = val.match(/^\[(.*)\]$/);
+  if (!m) {
+    throw new Error(`Skill ${source}: triggers.${key} must be an inline array like ["a", "b"]`);
+  }
+  return m[1]
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map(stripQuotes);
+}
+
+/**
+ * Walk a directory of skill files and return parsed skills. Missing dir
+ * returns []. Malformed files throw so the user sees the error early.
+ */
+export function loadSkillsFromDir(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const skills = [];
+  for (const name of fs.readdirSync(dir)) {
+    if (!name.endsWith(".md")) continue;
+    const filePath = path.join(dir, name);
+    const raw = fs.readFileSync(filePath, "utf8");
+    skills.push(parseSkill(raw, filePath));
+  }
+  return skills;
+}
+
+export function loadAllSkills() {
+  return [...loadSkillsFromDir(BUNDLED_SKILLS_DIR), ...loadSkillsFromDir(USER_SKILLS_DIR)];
+}
+
+/**
+ * Glob-to-regex converter for path patterns (supports `*` and `?`).
+ * Anchored: matches the full string, not a substring.
+ */
+export function globToRegex(glob) {
+  const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  const re = escaped.replace(/\*/g, ".*").replace(/\?/g, ".");
+  return new RegExp("^" + re + "$", "i");
+}
+
+/**
+ * Decide which skills' bodies should be appended to the system prompt for
+ * a given turn. A skill matches if ANY of its triggers fire:
+ *   - a promptKeyword appears in the user's prompt (case-insensitive)
+ *   - a pathPattern matches any file path in `referencedPaths`
+ * Returns the matching skills in insertion order (bundled before user).
+ */
+export function selectSkills({ skills, prompt = "", referencedPaths = [] }) {
+  const lowerPrompt = (prompt || "").toLowerCase();
+  const out = [];
+  for (const s of skills) {
+    const kwHit = s.triggers.promptKeywords.some((kw) =>
+      lowerPrompt.includes(kw.toLowerCase()),
+    );
+    const pathHit =
+      !kwHit &&
+      s.triggers.pathPatterns.some((g) => {
+        const re = globToRegex(g);
+        return referencedPaths.some((p) => re.test(path.basename(p)));
+      });
+    if (kwHit || pathHit) out.push(s);
+  }
+  return out;
+}
+
+/**
+ * Build the text block to append to the system prompt when one or more
+ * skills are active for this turn. Empty string when nothing matched.
+ */
+export function renderSkillsBlock(activeSkills) {
+  if (activeSkills.length === 0) return "";
+  const sections = activeSkills.map((s) => `### Skill: ${s.name}\n${s.body}`);
+  return (
+    "\n\n=== LOADED SKILLS (apply when relevant to this turn) ===\n\n" +
+    sections.join("\n\n---\n\n")
+  );
+}