Attempts at agent skills

kernel/share/agent-workspace/AGENTS.md

@@ -18,6 +18,13 @@
 - Append new facts, patterns, and observations to MEMORY.md.
 - Never edit SOUL.md or AGENTS.md in the same session (drift guard).
 
+## Skills usage rules
+
+- At the start of every complex task, check the available skills index in the system prompt.
+- If a relevant skill exists, call **`read_skill`** and follow its `SKILL.md` instructions exactly.
+- Log skill usage in MEMORY.md (which skill, why).
+- Never bypass security boundaries defined in any `SKILL.md`.
+
 ## Workflows
 
 - For complex tasks: think out loud → plan → execute → report results and changes.

kernel/share/agent-workspace/BOOTSTRAP.md

@@ -1,5 +1,6 @@
 # BOOTSTRAP.md - On Every Startup
 
-1. Check Hyperdrive health and current peer count
-2. Summarize recent changes from MEMORY.md
-3. Provide a concise 3-bullet status overview of the bare OS
+1. Check Hyperdrive health and peer count
+2. Discover and list available skills from `workspace/skills/` (compact index is in the system prompt; use `read_skill` when needed)
+3. Summarize recent MEMORY.md changes
+4. Provide a concise 3-bullet OS status overview

kernel/share/agent-workspace/README-agent.md

@@ -7,11 +7,23 @@ This tree follows the **agent** Markdown workspace convention: “soul” files
 | Path | Role |
 | --- | --- |
 | **`~/.agent/workspace/`** | Agent brain — **git-trackable**, portable across peers |
+| **`~/.agent/workspace/skills/`** | Modular **skills** — one folder per skill, each with **`SKILL.md`** (optional YAML frontmatter) |
 | **`~/.agent/workspace/memory/`** | Daily append logs `YYYY-MM-DD.md` (optional) |
+| **`~/.agent/skills/`** | Optional **global** skills (lower precedence than `workspace/skills/` when names collide) |
 | **`~/.agent/config.json`** | API URL, key, model (existing agent config) |
+| **`~/.agent/skill-loader.js`** | Host stub for `discoverSkills` / `loadSkill` (in-image agent uses bundled discovery + **`read_skill`** tool) |
 | **`~/.agent/loader.js`** | Stub / hook for **host-side** experimentation (not used by `/bin/agent` bundle) |
 | **`~/.agent/index.js`** | Stub factory reference (in-image agent uses built-in loader) |
 
+## Skills
+
+1. Add a directory under **`~/.agent/workspace/skills/<skill-id>/`** with a **`SKILL.md`** file.
+2. Use YAML frontmatter for **`name`**, **`description`**, **`version`**, etc. The compact system prompt lists **id**, **name**, and a short **description** only.
+3. During a session, the model loads the full document with the **`read_skill`** tool (do not paste huge skills into the user channel unless asked).
+4. Shared skills can live under **`~/.agent/skills/`**; keep **`workspace/skills/`** for machine-local or repo-specific behavior.
+
+Seeded examples in this repo (under **`skills/`**): **`p2p-os-status`** (P2P / drive health style checks) and **`bare-os-kernel-proc`** (authoritative **`/proc/bare_os/*`** reads vs man-page guessing).
+
 ## Editing
 
 1. Change files under **`~/.agent/workspace/`** on your **personal** drive.

kernel/share/agent-workspace/TOOLS.md

@@ -1,7 +1,17 @@
 # TOOLS.md - Available Capabilities
 
+## Core OS tools
+
 - **VFS / Hyperdrive** — read/write paths via agent tools (`read_file`, `write_file`, `list_directory`, …) on system and personal drives.
 - **`web_fetch`** — live `http(s)` fetches **only** when the operator allows them (`ctx.httpFetch`, `BARE_OS_HTTP_ALLOWLIST` / denylist). Same policy as delegated `curl` / `wget`.
 - **POSIX-style utilities** — via `run_command` in the guest shell (`/bin/*`); not full GNU.
 - **Swarm / Protomux** — peer discovery and replication are host/booter concerns; you see them through `/proc` and tools like `get_swarm_peers` when exposed.
 - **Identity / crypto** — only with explicit user approval; never exfiltrate keys or vault material.
+
+## Skills system
+
+The agent has access to modular **skills** under `~/.agent/workspace/skills/` (and optionally shared skills under `~/.agent/skills/`).
+
+- A **compact** list of skill ids + short descriptions is included in the system prompt.
+- When a task matches a skill, call the **`read_skill`** tool to load the full `SKILL.md`, then follow it exactly.
+- Prefer using skills over reinventing workflows.

kernel/share/agent-workspace/index.stub.js

@@ -5,6 +5,7 @@
  * The stock OS agent is /bin/agent (bare-os-coreutils bundle).
  */
 import { loadWorkspace } from './loader.js'
+export { discoverSkills, loadSkill } from './skill-loader.js'
 
 export async function createAgent(_llmInstance) {
   const systemPrompt = await loadWorkspace()

kernel/share/agent-workspace/loader.stub.js

@@ -2,7 +2,8 @@
  * Optional ~/.agent/loader.js (seeded stub)
  *
  * In-guest /bin/agent loads ~/.agent/workspace/*.md via the bundled
- * bareAgentLoadWorkspacePrompt() — it does not import this file.
+ * bareAgentLoadWorkspacePrompt() and appends a compact skills index +
+ * read_skill instructions — it does not import this file.
  * Use this stub on the host (Node/Bare) if you build a custom harness that
  * mirrors the agent loadWorkspace() pattern with bare-fs or Hyperdrive.
  */

kernel/share/agent-workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-os-agent-workspace",
   "private": true,
-  "description": "Markdown workspace templates for ~/.agent/workspace (agent-style). Not published to npm.",
+  "description": "Markdown workspace + skills templates for ~/.agent/workspace (agent-style). Not published to npm.",
   "version": "0.0.0"
 }

kernel/share/agent-workspace/skill-loader.stub.js

@@ -0,0 +1,21 @@
+/**
+ * Optional ~/.agent/skill-loader.js (seeded stub)
+ *
+ * In-guest /bin/agent discovers skills with bundled bareAgentDiscoverSkills and
+ * loads full SKILL.md via the read_skill tool (ctx.vfs). This file is for host
+ * projects that wire their own Hyperdrive/bare-fs harness.
+ */
+export async function discoverSkills() {
+  throw new Error(
+    'bare-os: implement discoverSkills with readdir/readFile on ~/.agent/workspace/skills (and optionally ~/.agent/skills), or use /bin/agent read_skill.'
+  )
+}
+
+/**
+ * @param {string} _skillName
+ */
+export async function loadSkill(_skillName) {
+  throw new Error(
+    'bare-os: implement loadSkill by reading <skills-dir>/<id>/SKILL.md, or use /bin/agent read_skill.'
+  )
+}

kernel/share/agent-workspace/skills/bare-os-kernel-proc/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: bare-os-kernel-proc
+version: 1.0.0
+description: Read kernel feature flags and capability JSON from /proc/bare_os (authoritative runtime state, not man keywords).
+tags: [kernel, proc, capabilities, debugging]
+requires: [read_proc_file, vfs]
+---
+
+# bare-os-kernel-proc Skill
+
+## When to use
+
+Use when the user asks what kernel features are **on or off in this session**, what capabilities exist, or whether something (SSH, replication, metrics) is actually enabled. Do **not** infer live kernel state from **`read_man_page`** / **`apropos_man`** alone — those search documentation text.
+
+## Execution steps
+
+1. Call **`read_proc_file`** on **`/proc/bare_os/features`** or **`/proc/bare_os/features.json`** (same payload shape as documented in the static system prompt).
+2. Call **`read_proc_file`** on **`/proc/bare_os/capabilities.json`** for structured capability bits.
+3. Optionally read **`/proc/bare_os/metrics_live.json`** or related **`/proc/bare_os/*`** paths if the question is about live metrics (stay within tool allowlists).
+4. Use **`get_system_info`** with **`want: capabilities`** or **`want: swarm`** only as a convenience when you already need bundled blobs; prefer **`read_proc_file`** for “what is enabled **now**?”.
+
+## Output format
+
+- **Sources**: list which `/proc/bare_os/*` files you read.
+- **Summary**: 3–6 bullets of what is enabled/disabled or missing, in plain language.
+- **Gaps**: if a path is missing or empty, say so — do not guess from docs.
+
+## Constraints
+
+- Read-only unless the user explicitly asks for a change that is allowed by **`AGENTS.md`** and tools policy.
+- Do not paste large JSON verbatim into the user channel unless asked; summarize first.

kernel/share/agent-workspace/skills/p2p-os-status/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: p2p-os-status
+version: 1.0.0
+description: Check and report health of the bare operating system, Hyperdrive, and Hyperswarm peers.
+tags: [p2p, hyperdrive, monitoring]
+requires: [bare-fs, hyperswarm]
+---
+
+# p2p-os-status Skill
+
+## When to use
+
+Use this skill whenever the user asks for system status, peer count, drive health, or debugging P2P connectivity.
+
+## Execution steps
+
+1. Use **`list_directory`** / **`read_file`** on relevant **`/home/...`** paths (personal vs system) when the question is about files on Hyperdrive.
+2. Call **`get_swarm_peers`** (and **`get_system_info`** as needed) for swarm / session context when exposed by the booter.
+3. Use **`read_proc_file`** on **`/proc/bare_os/*`** mirrors when the user cares about kernel/session metrics (see the **bare-os-kernel-proc** skill for feature/capability JSON).
+4. Check SSH/kernel narrative only when **`read_proc_file`** or **`read_man_page`** confirms how this image exposes **`sshd`** (do not assume **`node`** exists).
+4. Summarize in clear bullet points:
+
+   - Drive sync status
+   - Active peers
+   - Any warnings or errors
+   - Recent MEMORY.md highlights
+
+## Output Format
+
+Always respond with:
+
+- **Status Overview** (3-5 bullets)
+- **Peer Summary**
+- **Recommended Actions** (if any)
+
+Do not perform any write operations unless explicitly instructed.