@agentprojectcontext/apx 1.11.0 → 1.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"

package/skills/apc-context/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: apc-context
+description: "ALWAYS activate when the project has a .apc/ directory or AGENTS.md file. Do not wait to be asked. Read .apc/ before making any assumption about agents, memory, or project structure. Activate on: .apc/, AGENTS.md, 'which agents', 'list agents', 'agent context', 'who are the agents', any question about agents or memory in this project. IMPORTANT: if .apc/migrate.md exists, open the conversation with a migration offer before answering anything else. If the user declines, delete .apc/migrate.md immediately so it is not shown again."
+homepage: https://github.com/agentprojectcontext/apx
+---
+
+# Agent Project Context
+
+This project uses APC. APC stores portable project context in `.apc/` and `AGENTS.md`.
+
+APC does not store raw runtime sessions. Sessions, conversations, messages, caches, provider
+threads, and private runtime memory stay in the IDE, CLI, daemon, or user-level store that created
+them.
+
+## FIRST: check for pending migration
+
+Before doing anything else, check if `.apc/migrate.md` exists:
+
+```bash
+cat .apc/migrate.md 2>/dev/null
+```
+
+If it exists, offer to migrate before answering anything else. Read detected files, separate durable
+project context from runtime/private state, and migrate only what belongs in APC.
+
+If the user says no or later, delete `.apc/migrate.md` so the offer is not repeated.
+
+## Migration rule: think, do not copy
+
+Classify content:
+
+| Content | Action |
+|---|---|
+| Agent definitions: role, model, skills, description | Put in `.apc/agents/<slug>.md` and/or `AGENTS.md` |
+| Shared project rules, stack notes, commands, testing policy | Keep in `AGENTS.md` |
+| Reusable instruction blocks | Move to `.apc/skills/<name>.md` |
+| Durable safe facts useful to all contributors | Add to `.apc/agents/<slug>/memory.md` only after curation |
+| MCP expectations without secrets | Add to `.apc/mcps.json` |
+| Raw sessions, transcripts, conversations, messages, tool logs | Do not move into `.apc/`; leave with source runtime |
+| Secrets, tokens, credentials, private headers | Do not store in repository |
+| IDE UI settings or personal aliases | Leave in IDE/user config |
+| Instructions to store sessions under `.apc/` | Drop as obsolete |
+
+## APC structure
+
+```text
+AGENTS.md                        ← root project contract
+.apc/
+  project.json                   ← project metadata
+  .gitignore                     ← safety guard
+  agents/<slug>.md               ← agent definition
+  agents/<slug>/memory.md        ← optional curated project memory
+  skills/<name>.md               ← reusable project instructions
+  mcps.json                      ← MCP hints without secrets
+```
+
+Do not store:
+
+```text
+.apc/agents/<slug>/sessions/
+.apc/sessions/
+.apc/conversations/
+.apc/messages/
+.apc/project.db
+.apc/cache/
+.apc/tmp/
+.apc/private/
+.apc/secrets/
+```
+
+## Operating rules
+
+1. Read `AGENTS.md` and relevant `.apc/` files before assuming project context.
+2. Read agent definitions from `.apc/agents/<slug>.md` when present.
+3. Read curated project memory from `.apc/agents/<slug>/memory.md` when present.
+4. Write only durable, safe, curated facts to APC memory.
+5. Never write raw sessions, transcripts, messages, conversations, or tool logs into `.apc/`.
+6. Keep secrets out of APC and out of git.
+7. Treat `.apc/mcps.json` as MCP configuration hints, not as an MCP implementation.
+
+## Sessions
+
+Sessions belong to the runtime that created them.
+
+Examples:
+
+```text
+Codex runtime storage
+Claude Code runtime storage
+OpenCode runtime storage
+~/.apx/projects/<project-id>/agents/<slug>/sessions/
+```
+
+At task end, provide the user a concise result. If project memory should be updated, write a short
+sanitized fact to `.apc/agents/<slug>/memory.md` only when useful and safe.
+
+## APX
+
+APX can provide a local daemon, MCP management, Telegram bridge, routines, and runtime dispatch
+across Codex, Claude Code, OpenCode, Aider, Cursor Agent, Gemini CLI, Qwen Code, or direct LLM
+engines. Those are APX runtime features, not APC portable-core requirements.
+
+The APX super-agent uses `~/.apx/projects/default` for system-level work when no project is named.
+APX routines can run heartbeat, shell, Telegram, project agent, or super-agent tasks on a schedule.
+
+APX runtime state belongs outside the repository:
+
+```text
+~/.apx/projects/<project-id>/
+```

package/src/cli/commands/sys.js

@@ -359,9 +359,14 @@ async function runPrompt(pid, state, previousMessages, renderScreen, text, userI
   const startTime = Date.now();
 
   try {
+    const cwd = process.cwd();
     const body = {
       prompt: `[Mode: ${MODES[state.currentModeIdx]}]\n${text}`,
-      contextNote: "Channel: terminal. Format freely using markdown, but keep it readable. Use code diffs when editing.",
+      contextNote: [
+        "Channel: terminal. Format freely using markdown, but keep it readable. Use code diffs when editing.",
+        `CWD: ${cwd}`,
+        "When the user says \"este directorio\", \"este proyecto\", \"acá\", \"aquí\", \"this directory\", \"current dir\" or any equivalent reference without naming a path, they mean exactly the CWD above. Use it as the path argument directly — don't ask the user to provide it.",
+      ].join("\n"),
       previousMessages,
       model: state.activeModel,
     };

package/src/daemon/skills-loader.js

@@ -0,0 +1,228 @@
+// daemon/skills-loader.js
+// Discover and load APX skills on-demand for the super-agent.
+//
+// The super-agent reads skills from immutable INTERNAL sources under
+// src/core/ — they ship with apx and can never be deleted by the user. This
+// guarantees apx/apc/runtime knowledge is always available regardless of
+// what the user does to ~/.apx/skills/. Distribution copies under
+// <package>/skills/ are a separate concern (scaffold.js handles them) and
+// the loader does NOT read from there.
+//
+// Discovery order (priority high → low):
+//   1. <projectPath>/.apc/skills/<slug>.md          ← project-scoped
+//   1b.<projectPath>/.apc/skills/<slug>/SKILL.md    ← same, dir-style
+//   2. ~/.apx/skills/<slug>/SKILL.md                ← user-installed global
+//   3. <packageRoot>/src/core/runtime-skills/<slug>.md ← built-in runtime docs
+//                                                       (claude-code, codex-cli,
+//                                                       opencode-cli, openrouter)
+//   4. <packageRoot>/src/core/apx-skill.md          ← built-in intrinsic apx
+//   4b.<packageRoot>/src/core/apc-context-skill.md  ← built-in intrinsic apc-context
+//
+// A slug found in a higher-priority location SHADOWS lower ones — so a user
+// who drops `~/.apx/skills/apx/SKILL.md` overrides the intrinsic one, but the
+// intrinsic stays in the package as a safety net.
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname  = path.dirname(__filename);
+const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
+
+const RUNTIME_SKILLS_DIR = path.join(PACKAGE_ROOT, "src", "core", "runtime-skills");
+const GLOBAL_DIR         = path.join(os.homedir(), ".apx", "skills");
+const CORE_DIR           = path.join(PACKAGE_ROOT, "src", "core");
+
+// Intrinsic built-in skills whose source files (src/core/*-skill.md) do NOT
+// carry frontmatter — the scaffold.js wrapper adds frontmatter when copying
+// these out to external IDE skill dirs. For the super-agent's catalog we
+// supply slug + description inline. Keep in sync with scaffold.js.
+const INTRINSIC = [
+  {
+    slug: "apx",
+    file: path.join(CORE_DIR, "apx-skill.md"),
+    description:
+      "APX CLI skill. Activate when: user asks to run or coordinate agents, " +
+      "use MCP tools from .apc/mcps.json, install agents from a team workspace, " +
+      "or explicitly mentions apx commands. Do NOT activate just because .apc/ exists — " +
+      "that is handled by the apc-context skill. Activate on: 'apx run', 'apx exec', " +
+      "'run an agent', 'coordinate agents', 'MCP not working', 'install agent', " +
+      "'team agents', 'apx memory', 'daemon'.",
+  },
+  {
+    slug: "apc-context",
+    file: path.join(CORE_DIR, "apc-context-skill.md"),
+    description:
+      "ALWAYS activate when the project has a .apc/ directory or AGENTS.md file. " +
+      "Do not wait to be asked. Read .apc/ before making any assumption about agents, " +
+      "memory, or project structure. Activate on: .apc/, AGENTS.md, 'which agents', " +
+      "'list agents', 'agent context', 'who are the agents', any question about agents " +
+      "or memory in this project. IMPORTANT: if .apc/migrate.md exists, open the " +
+      "conversation with a migration offer before answering anything else. If the user " +
+      "declines, delete .apc/migrate.md immediately so it is not shown again.",
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Frontmatter parsing (minimal — handles the YAML we ship)
+// ---------------------------------------------------------------------------
+
+function parseFrontmatter(raw) {
+  if (!raw.startsWith("---")) return { fm: {}, body: raw };
+  const end = raw.indexOf("\n---", 3);
+  if (end < 0) return { fm: {}, body: raw };
+
+  const fmBlock = raw.slice(3, end).trim();
+  const body = raw.slice(end + 4).replace(/^\n/, "");
+
+  const fm = {};
+  for (const line of fmBlock.split("\n")) {
+    const m = line.match(/^([a-zA-Z_][a-zA-Z0-9_-]*)\s*:\s*(.*)$/);
+    if (!m) continue;
+    let val = m[2].trim();
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1);
+    }
+    fm[m[1]] = val;
+  }
+  return { fm, body };
+}
+
+// ---------------------------------------------------------------------------
+// Directory scanners
+// ---------------------------------------------------------------------------
+
+/** Returns [{slug, source, file}] from a directory using <slug>/SKILL.md layout. */
+function scanDirStyle(baseDir, source) {
+  if (!baseDir || !fs.existsSync(baseDir)) return [];
+  const out = [];
+  let entries;
+  try { entries = fs.readdirSync(baseDir, { withFileTypes: true }); }
+  catch { return []; }
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const file = path.join(baseDir, e.name, "SKILL.md");
+    if (fs.existsSync(file)) out.push({ slug: e.name, source, file });
+  }
+  return out;
+}
+
+/** Returns [{slug, source, file}] from a directory using <slug>.md layout. */
+function scanFlatStyle(baseDir, source) {
+  if (!baseDir || !fs.existsSync(baseDir)) return [];
+  const out = [];
+  let entries;
+  try { entries = fs.readdirSync(baseDir, { withFileTypes: true }); }
+  catch { return []; }
+  for (const e of entries) {
+    if (!e.isFile() || !e.name.endsWith(".md")) continue;
+    if (e.name === "README.md") continue;
+    out.push({
+      slug: e.name.replace(/\.md$/, ""),
+      source,
+      file: path.join(baseDir, e.name),
+    });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Discover available skills across all locations.
+ * Returns lightweight metadata only — body is NOT read.
+ *
+ * @param {object} opts
+ * @param {string=} opts.projectPath  optional project root to also scan
+ * @returns {Array<{slug, source, description, file}>}
+ */
+export function listSkills({ projectPath } = {}) {
+  const found = [];
+
+  // priority 1: project-scoped
+  if (projectPath) {
+    const apcSkills = path.join(projectPath, ".apc", "skills");
+    found.push(...scanDirStyle(apcSkills, "project"));
+    found.push(...scanFlatStyle(apcSkills, "project"));
+  }
+
+  // priority 2: user-installed global
+  found.push(...scanDirStyle(GLOBAL_DIR, "global"));
+
+  // priority 3: built-in runtime docs (have frontmatter)
+  found.push(...scanFlatStyle(RUNTIME_SKILLS_DIR, "builtin"));
+
+  // priority 4: intrinsic built-ins (no frontmatter — descriptions hardcoded)
+  for (const it of INTRINSIC) {
+    if (fs.existsSync(it.file)) {
+      found.push({ slug: it.slug, source: "builtin", file: it.file, _description: it.description });
+    }
+  }
+
+  // dedupe by slug (first-wins = higher priority shadows lower)
+  const seen = new Set();
+  const result = [];
+  for (const entry of found) {
+    if (seen.has(entry.slug)) continue;
+    seen.add(entry.slug);
+
+    // Description: prefer inline (intrinsic) → frontmatter → empty
+    let description = entry._description || "";
+    if (!description) {
+      try {
+        const raw = fs.readFileSync(entry.file, "utf8");
+        const { fm } = parseFrontmatter(raw);
+        description = fm.description || "";
+      } catch { /* unreadable — skip description */ }
+    }
+
+    result.push({
+      slug: entry.slug,
+      source: entry.source,
+      description,
+      file: entry.file,
+    });
+  }
+  return result;
+}
+
+/**
+ * Load the full body of a skill (frontmatter stripped if present). Resolves
+ * via the same priority chain as listSkills().
+ *
+ * @param {string} slug
+ * @param {object} opts
+ * @param {string=} opts.projectPath
+ * @returns {{slug, source, file, description, body, frontmatter}}
+ */
+export function loadSkill(slug, { projectPath } = {}) {
+  if (!slug) throw new Error("loadSkill: slug required");
+
+  const list = listSkills({ projectPath });
+  const entry = list.find(s => s.slug === slug);
+  if (!entry) {
+    throw new Error(`skill "${slug}" not found. Available: ${list.map(s => s.slug).join(", ") || "(none)"}`);
+  }
+
+  const raw = fs.readFileSync(entry.file, "utf8");
+  const { fm, body } = parseFrontmatter(raw);
+  return {
+    slug: entry.slug,
+    source: entry.source,
+    file: entry.file,
+    description: entry.description || fm.description || "",
+    frontmatter: fm,
+    body: body.trim(),
+  };
+}
+
+// Useful for diagnostics
+export const SKILL_LOCATIONS = {
+  runtime_skills: RUNTIME_SKILLS_DIR,
+  intrinsic: CORE_DIR,
+  global: GLOBAL_DIR,
+};

package/src/daemon/super-agent-tools/index.js

@@ -19,9 +19,12 @@ import sendTelegram from "./tools/send-telegram.js";
 import setIdentity from "./tools/set-identity.js";
 import setPermissionMode from "./tools/set-permission-mode.js";
 import searchFiles from "./tools/search-files.js";
+import listSkills from "./tools/list-skills.js";
+import loadSkill from "./tools/load-skill.js";
 import { createPermissionGuard } from "./helpers.js";
+import { buildBridgedTools, DEFAULT_CATEGORIES } from "./registry-bridge.js";
 
-const TOOLS = [
+const NATIVE_TOOLS = [
   listProjects,
   listAgents,
   listVaultAgents,
@@ -43,8 +46,22 @@ const TOOLS = [
   setIdentity,
   setPermissionMode,
   searchFiles,
+  listSkills,
+  loadSkill,
 ];
 
+// Registry-backed bridges. Categories can be overridden per-process via env
+// APX_BRIDGE_CATEGORIES (comma-separated), e.g. "browser,fetch,search".
+// Default: browser, fetch, search, glob, grep (see registry-bridge.js).
+function resolveBridgeCategories() {
+  const env = (process.env.APX_BRIDGE_CATEGORIES || "").trim();
+  if (!env) return DEFAULT_CATEGORIES;
+  return new Set(env.split(",").map(s => s.trim()).filter(Boolean));
+}
+
+const BRIDGED_TOOLS = buildBridgedTools({ categories: resolveBridgeCategories() });
+const TOOLS = [...NATIVE_TOOLS, ...BRIDGED_TOOLS];
+
 export const TOOL_SCHEMAS = TOOLS.map((tool) => tool.schema);
 
 export function makeToolHandlers(ctx) {
@@ -56,3 +73,8 @@ export function makeToolHandlers(ctx) {
   };
   return Object.fromEntries(TOOLS.map((tool) => [tool.name, tool.makeHandler(toolCtx)]));
 }
+
+// Diagnostic helper — useful for `apx daemon status` or debug logging.
+export function listBridgedToolNames() {
+  return BRIDGED_TOOLS.map(t => t.name);
+}

package/src/daemon/super-agent-tools/registry-bridge.js

@@ -0,0 +1,122 @@
+// daemon/super-agent-tools/registry-bridge.js
+//
+// Generic bridge that exposes registry-backed HTTP tools (browser, fetch,
+// search, glob, grep, etc.) to the super-agent — no per-tool import boilerplate.
+//
+// How it works:
+//   1. Read TOOL_DEFINITIONS from daemon/tools/registry.js
+//   2. Drop entries whose names collide with native super-agent tools (those
+//      win — they touch in-process state directly).
+//   3. For each remaining entry, produce { name, schema, makeHandler } in the
+//      exact shape index.js expects, so they slot into TOOL_SCHEMAS alongside
+//      the native ones.
+//   4. The generated handler POSTs/GETs to the daemon's own HTTP server on
+//      127.0.0.1:<port>. Yes, the super-agent talks to its own daemon — that
+//      keeps the bridge dead-simple, lets the engine adapter format tool
+//      schemas uniformly, and reuses the exact code path external callers hit.
+//
+// Net result: adding a tool = adding one entry to registry.js. No file in
+// super-agent-tools/tools/, no import in index.js.
+
+import { TOOL_DEFINITIONS } from "../tools/registry.js";
+
+// Native handlers in super-agent-tools/tools/ that own these names. The bridge
+// MUST skip them or the registry version (HTTP roundtrip) would shadow the
+// native one with possibly different semantics.
+const NATIVE_NAMES = new Set([
+  "list_projects", "list_agents", "list_vault_agents", "import_agent",
+  "add_project", "list_mcps", "read_agent_memory",
+  "list_files", "read_file", "write_file", "edit_file", "search_files",
+  "run_shell", "tail_messages", "search_messages",
+  "call_agent", "call_mcp", "call_runtime",
+  "send_telegram", "set_identity", "set_permission_mode",
+]);
+
+// Default allow-list of categories the bridge will expose. The NATIVE_NAMES
+// filter handles duplicates inside these categories (e.g. "file" contains
+// both read_file [native] and glob [bridged]). Anything outside is ignored
+// — "shell"/"mcp"/"memory"/"session" have different semantics handled
+// natively. Override with env APX_BRIDGE_CATEGORIES.
+const DEFAULT_CATEGORIES = new Set(["browser", "fetch", "search", "file"]);
+
+function buildSchema(entry) {
+  return {
+    type: "function",
+    function: {
+      name: entry.name,
+      description: entry.description,
+      parameters: entry.parameters || { type: "object", properties: {} },
+    },
+  };
+}
+
+function buildHandler(entry) {
+  return ({ globalConfig }) => async (args = {}) => {
+    const port = globalConfig?.port || process.env.APX_PORT || 7430;
+    const method = String(entry.endpoint?.method || "POST").toUpperCase();
+    let url = `http://127.0.0.1:${port}${entry.endpoint?.path || ""}`;
+
+    const opts = {
+      method,
+      headers: { "content-type": "application/json" },
+    };
+
+    if (method === "GET" || method === "HEAD") {
+      const qs = new URLSearchParams();
+      for (const [k, v] of Object.entries(args)) {
+        if (v === undefined || v === null) continue;
+        qs.set(k, typeof v === "object" ? JSON.stringify(v) : String(v));
+      }
+      const q = qs.toString();
+      if (q) url += (url.includes("?") ? "&" : "?") + q;
+    } else {
+      opts.body = JSON.stringify(args);
+    }
+
+    let res, text;
+    try {
+      res = await fetch(url, opts);
+      text = await res.text();
+    } catch (e) {
+      return { error: `bridge fetch failed: ${e.message}`, url };
+    }
+
+    let parsed;
+    try { parsed = JSON.parse(text); }
+    catch { parsed = { raw: text }; }
+
+    if (!res.ok) {
+      return {
+        error: parsed?.error || `HTTP ${res.status}`,
+        status: res.status,
+        ...(typeof parsed === "object" ? parsed : {}),
+      };
+    }
+    return parsed;
+  };
+}
+
+/**
+ * Returns an array of tool objects in the shape super-agent-tools/index.js
+ * expects: { name, schema, makeHandler }.
+ *
+ * @param {object} opts
+ * @param {Set<string>=} opts.categories   override DEFAULT_CATEGORIES
+ * @param {Set<string>=} opts.skipNames    extra names to skip in addition to NATIVE_NAMES
+ */
+export function buildBridgedTools(opts = {}) {
+  const categories = opts.categories instanceof Set ? opts.categories : DEFAULT_CATEGORIES;
+  const skipNames = opts.skipNames instanceof Set ? opts.skipNames : new Set();
+
+  return TOOL_DEFINITIONS
+    .filter(e => categories.has(e.category))
+    .filter(e => !NATIVE_NAMES.has(e.name) && !skipNames.has(e.name))
+    .filter(e => e.endpoint?.path)
+    .map(entry => ({
+      name: entry.name,
+      schema: buildSchema(entry),
+      makeHandler: buildHandler(entry),
+    }));
+}
+
+export { NATIVE_NAMES, DEFAULT_CATEGORIES };

package/src/daemon/super-agent-tools/tools/add-project.js

@@ -1,36 +1,66 @@
+import fs from "node:fs";
 import path from "node:path";
 import { readConfig, addProject as addProjectInConfig } from "../../../core/config.js";
+import { initApf } from "../../../core/scaffold.js";
 import { confirmedProperty, projectMeta } from "../helpers.js";
 
+function isApcProject(absPath) {
+  return (
+    fs.existsSync(path.join(absPath, "AGENTS.md")) &&
+    fs.existsSync(path.join(absPath, ".apc", "project.json"))
+  );
+}
+
 export default {
   name: "add_project",
   schema: {
     type: "function",
     function: {
       name: "add_project",
-      description: "Register an existing APC project path with the APX daemon. The path must contain AGENTS.md and .apc/project.json.",
+      description:
+        "Register a project path with the APX daemon. If the path is not yet an APC project (missing AGENTS.md or .apc/project.json), the tool runs the init scaffold first and then registers it — one call covers both cases. Pass init=false to require the path to already be an APC project (strict mode).",
       parameters: {
         type: "object",
         properties: {
-          path: { type: "string", description: "absolute or relative filesystem path to an APC project" },
+          path: { type: "string", description: "absolute or relative filesystem path to add" },
+          name: { type: "string", description: "optional project name (used only when initializing a new APC project)" },
+          init: { type: "boolean", description: "auto-create AGENTS.md and .apc/project.json if missing (default true)" },
           confirmed: confirmedProperty("true only after explicit user confirmation for this exact project registration"),
         },
         required: ["path"],
       },
     },
   },
-  makeHandler: ({ projects, requirePermission }) => ({ path: projectPath, confirmed = false }) => {
+  makeHandler: ({ projects, requirePermission }) => ({ path: projectPath, name, init = true, confirmed = false }) => {
     requirePermission("add_project", { dangerous: true, confirmed });
     if (!projectPath) throw new Error("add_project: path required");
 
+    const abs = path.resolve(projectPath);
+    if (!fs.existsSync(abs)) {
+      throw new Error(`add_project: path does not exist: ${abs}`);
+    }
+
+    let initialized = false;
+    if (!isApcProject(abs)) {
+      if (!init) {
+        throw new Error(
+          `not an APC project: ${abs} (no AGENTS.md / .apc/project.json). ` +
+          `Pass init=true to scaffold it before registering.`
+        );
+      }
+      initApf(abs, { name });
+      initialized = true;
+    }
+
     const cfg = readConfig();
-    const result = addProjectInConfig(cfg, projectPath);
+    const result = addProjectInConfig(cfg, abs);
     const p = projects.register(result.project.path);
     return {
       ok: true,
       added: result.added,
+      initialized,
       project: projectMeta(projects, p),
-      normalized_path: path.resolve(projectPath),
+      normalized_path: abs,
     };
   },
 };

package/src/daemon/super-agent-tools/tools/list-skills.js

@@ -0,0 +1,32 @@
+import { listSkills, SKILL_LOCATIONS } from "../../skills-loader.js";
+
+export default {
+  name: "list_skills",
+  schema: {
+    type: "function",
+    function: {
+      name: "list_skills",
+      description:
+        "List available skills (documentation modules) the super-agent can load on demand. Returns slug + 1-line description for each — NO body content (cheap). Call load_skill(slug) to actually fetch the doc when needed. Scans built-in skills shipped with apx, user-installed globals in ~/.apx/skills/, and project-scoped skills in <project>/.apc/skills/.",
+      parameters: {
+        type: "object",
+        properties: {
+          project_path: {
+            type: "string",
+            description: "optional project root to also scan for project-scoped skills (use the CWD when the user is working in a project)",
+          },
+        },
+      },
+    },
+  },
+  makeHandler: () => ({ project_path } = {}) => {
+    const skills = listSkills({ projectPath: project_path });
+    return {
+      ok: true,
+      count: skills.length,
+      locations: SKILL_LOCATIONS,
+      project_path: project_path || null,
+      skills: skills.map(({ slug, source, description }) => ({ slug, source, description })),
+    };
+  },
+};

package/src/daemon/super-agent-tools/tools/load-skill.js

@@ -0,0 +1,31 @@
+import { loadSkill } from "../../skills-loader.js";
+
+export default {
+  name: "load_skill",
+  schema: {
+    type: "function",
+    function: {
+      name: "load_skill",
+      description:
+        "Load the full body of a named skill (markdown documentation, frontmatter stripped). Use after list_skills found a relevant slug. Resolves the slug via priority: project > global (~/.apx/skills/) > built-in. The body is loaded into the conversation only on the turn you call this — keeps baseline tokens at zero.",
+      parameters: {
+        type: "object",
+        properties: {
+          slug: {
+            type: "string",
+            description: "skill slug as listed by list_skills (e.g. \"apx\", \"apc-context\")",
+          },
+          project_path: {
+            type: "string",
+            description: "optional project root for resolving project-scoped skills",
+          },
+        },
+        required: ["slug"],
+      },
+    },
+  },
+  makeHandler: () => ({ slug, project_path } = {}) => {
+    if (!slug) throw new Error("load_skill: slug required");
+    return loadSkill(slug, { projectPath: project_path });
+  },
+};

package/src/daemon/super-agent.js

@@ -13,6 +13,7 @@
 //   }
 import { callEngine } from "./engines/index.js";
 import { TOOL_SCHEMAS, makeToolHandlers } from "./super-agent-tools.js";
+import { listSkills } from "./skills-loader.js";
 import {
   extractPseudoToolCalls,
   cleanTextOfPseudoToolCalls,
@@ -61,7 +62,10 @@ HARD RULES (do not deviate):
 15. NO-PENDING RULE: never say "give me a second", "I will do it", or "I will try later" as a final answer. Either call the tool in this same turn or say what blocks you.
 16. IDENTITY RULE: when the user asks you to change your name, call yourself something, or update your personality/language, call set_identity and persist the change. Then confirm with your new name.
 17. ROUTINES RULE: NEVER create a routine in the default project (id=0). Routines MUST be tied to a specific registered project. Before adding a routine, call list_projects to find the correct project id or name. Then pass --project <id|name> to apx routine add. If no project fits, ask the user which project to use. Creating routines in project 0/default mixes unrelated projects' schedules and corrupts state.
-18. **NO EMPTY RESPONSES**: Never respond with only text when you have tools available and the user is asking you to DO something. Call the tool FIRST, then explain. Never say "I'll do X" without immediately calling the tool. Empty acknowledgments ("ok", "entendido", "dame un minuto", "voy", "checking", "stand by") without a tool call are invalid responses — they will be re-prompted and waste a turn.`;
+18. **NO EMPTY RESPONSES**: Never respond with only text when you have tools available and the user is asking you to DO something. Call the tool FIRST, then explain. Never say "I'll do X" without immediately calling the tool. Empty acknowledgments ("ok", "entendido", "dame un minuto", "voy", "checking", "stand by") without a tool call are invalid responses — they will be re-prompted and waste a turn.
+19. **CWD RULE**: When the channel context includes a "CWD: <path>" line, that is the user's current working directory. References to "este directorio", "este proyecto", "esta carpeta", "acá", "aquí", "this directory", "this project", "current dir/folder" all mean that exact CWD path. Use it as the path argument directly — DO NOT ask the user "what's the path?" when CWD is already given. Example: if user says "agregá este proyecto a la lista", call add_project({path: <CWD>}) immediately.
+20. **NO MANUAL SCAFFOLDING**: To register or scaffold a project, ALWAYS use add_project — it auto-creates AGENTS.md and .apc/project.json when missing (one call, atomic). NEVER write AGENTS.md, .apc/project.json, or any APC scaffold file by hand via run_shell / write_file / shell pipes. The schema must come from the official initApf scaffold, not improvised. If add_project errors, report the error to the user — don't try to work around it with shell hacks. Same for any other APC-managed file (.apc/agents/*, .apc/skills/*, etc.) — use the dedicated tool, never raw filesystem writes.
+21. **SKILLS — ON DEMAND**: The "# Available skills" section below lists every skill available to you (slug + description, NO body). When the user asks about specific APX/APC commands, project structure, agent runtimes, or anything where exact syntax or detailed behavior matches a skill description (in ANY language — match semantically, not by keyword), call load_skill({slug}) to fetch the full markdown body. If a CWD is in the contextNote, pass it as project_path so project-scoped skills resolve. If the user explicitly asks "what skills do you have?", you can either read the catalog below directly OR call list_skills to get a fresh enumeration. Do NOT load skills for trivial / unrelated questions — that wastes tokens. Don't guess CLI syntax when a skill can tell you; load it.`;
 
 function isShortConfirmation(text) {
   return /^(yes|y|si|si dale|dale|ok|okay|confirm|confirmed|go|proceed|do it)\b/i
@@ -135,12 +139,32 @@ export async function runSuperAgent({
     "When a tool schema has confirmed, set confirmed=true only after explicit user confirmation for that exact action.",
   ].join("\n");
 
+  // Build a lightweight catalog of available skills (slug + 1-line description).
+  // Skill BODIES are NOT included — only the catalog. The model decides which
+  // (if any) to load on demand via load_skill(slug). Cross-lingual matching is
+  // handled by the LLM itself (no router needed). Empty if no skills found.
+  const skillsCatalog = (() => {
+    let list = [];
+    try { list = listSkills(); } catch { /* loader failure → empty catalog */ }
+    if (!list.length) return "";
+    return [
+      "# Available skills (load on demand)",
+      "Below is the catalog of skills (slug + description). Bodies are NOT loaded yet.",
+      "If the user asks how something works, requests syntax/docs, or otherwise needs",
+      "knowledge that matches a skill description (in any language — match semantically),",
+      "call load_skill({slug}) to load the full markdown into your context.",
+      "",
+      ...list.map(s => `- **${s.slug}** [${s.source}]: ${s.description || "(no description)"}`),
+    ].join("\n");
+  })();
+
   const system = [
     sa.system || DEFAULT_SYSTEM,
     permissionNote,
     contextNote,
     "# Registered projects (just the index — call tools for details)",
     projectIndex || "(no projects registered)",
+    skillsCatalog,
   ]
     .filter(Boolean)
     .join("\n\n");