Install skills once to the shared ~/.agents/skills folder

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to summer-engine will be documented here. Following [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+### Changed
+- Agents whose docs read the agentskills.io folder now install skills to `~/.agents/skills` (project: `.agents/skills`) instead of each agent's own folder: Codex, Cursor, Zed, OpenCode, Copilot in VS Code, Devin Desktop, Amp, Crush, Warp, Kimi Code, Factory Droid, Rovo Dev, Grok Build; Antigravity, Goose, Hermes and Mistral Vibe at project scope. One install serves all of them and "where are the skills" has one answer. `skills install --force` removes the copies 3.1.0 wrote in the old per-agent folders.
+
 ## [3.1.0] - 2026-09-11
 
 ### Added

docs/OVERVIEW.md

@@ -45,38 +45,38 @@ Or download from [summerengine.com/download](https://summerengine.com/download).
 
 ## Where skills live per agent
 
-Each agent has its own home for skills (`<skill>/SKILL.md` unless noted). Agents with no skills folder (Claude Desktop, Copilot in Visual Studio and JetBrains, Trae, Junie, LM Studio) get the MCP server only and pull guidance in-chat via `summer_get_agent_playbook`.
+Skills install as `<skill>/SKILL.md`. Agents whose docs read the agentskills.io folder (`~/.agents/skills`, `.agents/skills`) share it, so one install covers Codex, Cursor, Zed, OpenCode, Copilot in VS Code, Devin Desktop, Amp, Crush, Warp, Kimi, Factory, Rovo Dev and Grok Build; the rest keep their own folder. Agents with no skills folder (Claude Desktop, Copilot in Visual Studio and JetBrains, Trae, Junie, LM Studio) get the MCP server only and pull guidance in-chat via `summer_get_agent_playbook`.
 
 | Agent | User scope | Project scope |
 |---|---|---|
 | `summer` | `~/.summer/skills` | `.summer/skills` |
 | `claude-code` | `~/.claude/skills` | `.claude/skills` |
 | `codex` | `~/.agents/skills` | `.agents/skills` |
-| `cursor` | `~/.cursor/skills` | `.cursor/skills` |
-| `windsurf` | `~/.codeium/windsurf/skills` | `.windsurf/skills` |
+| `cursor` | `~/.agents/skills` | `.agents/skills` |
+| `windsurf` | `~/.agents/skills` | `.agents/skills` |
 | `antigravity` | `~/.gemini/config/skills` | `.agents/skills` |
 | `gemini` (legacy) | `~/.gemini/extensions/summer-engine/skills` | n/a |
 | `cline` | `~/.cline/skills` | `.cline/skills` |
 | `cline-cli` | `~/.cline/skills` | `.cline/skills` |
 | `roo-code` (legacy) | `~/Documents/Roo/Rules` (rule files `summer-<skill>.md`) | `.clinerules` |
 | `kilo-code` | `~/.kilo/skills` | `.kilo/skills` |
 | `github-copilot` | `~/.copilot/skills` | `.github/skills` |
-| `vscode-copilot` | `~/.copilot/skills` | `.github/skills` |
-| `opencode` | `~/.config/opencode/skills` | `.opencode/skills` |
+| `vscode-copilot` | `~/.agents/skills` | `.agents/skills` |
+| `opencode` | `~/.agents/skills` | `.agents/skills` |
 | `zed` | `~/.agents/skills` | `.agents/skills` |
 | `kiro` | `~/.kiro/skills` | `.kiro/skills` |
 | `goose` | `~/.config/agents/skills` | `.agents/skills` |
-| `hermes` | `~/.hermes/skills` | `.hermes/skills` |
+| `hermes` | `~/.hermes/skills` | `.agents/skills` |
 | `qwen-code` | `~/.qwen/skills` | `.qwen/skills` |
-| `kimi-code` | `~/.kimi-code/skills` | `.kimi-code/skills` |
-| `crush` | `~/.config/crush/skills` | `.crush/skills` |
-| `amp` | `~/.config/amp/skills` | `.agents/skills` |
-| `factory` | `~/.factory/skills` | `.factory/skills` |
-| `warp` | `~/.warp/skills` | `.warp/skills` |
-| `rovo-dev` | `~/.rovodev/skills` | `.rovodev/skills` |
+| `kimi-code` | `~/.agents/skills` | `.agents/skills` |
+| `crush` | `~/.agents/skills` | `.agents/skills` |
+| `amp` | `~/.agents/skills` | `.agents/skills` |
+| `factory` | `~/.agents/skills` | `.agents/skills` |
+| `warp` | `~/.agents/skills` | `.agents/skills` |
+| `rovo-dev` | `~/.agents/skills` | `.agents/skills` |
 | `qoder` | `~/.qoder/skills` | `.qoder/skills` |
-| `grok-build` | `~/.grok/skills` | `.grok/skills` |
-| `mistral-vibe` | `~/.vibe/skills` | `.vibe/skills` |
+| `grok-build` | `~/.agents/skills` | `.agents/skills` |
+| `mistral-vibe` | `~/.vibe/skills` | `.agents/skills` |
 
 Use `--scope project` when you want the skills committed with the game:
 

integrations/amp/README.md

@@ -6,7 +6,7 @@ is intentionally empty. Support is delivered at install time by
 
 - MCP config: `~/.config/amp/settings.json`; Windows `%APPDATA%/amp/settings.json` (user); user scope only (project requests fall back with a warning).
   Shape: `"amp.mcpServers".summer-engine = { command, args }`.
-- Skills: `~/.config/amp/skills` (user) or `.agents/skills` (project) as `<skill>/SKILL.md`.
+- Skills: `~/.agents/skills` (user) or `.agents/skills` (project) as `<skill>/SKILL.md`.
 - After: Restart Amp so it reloads settings.json.
 
 Source of truth: `src/installer/agent-table.ts` (one row per agent).

integrations/crush/README.md

@@ -6,7 +6,7 @@ is intentionally empty. Support is delivered at install time by
 
 - MCP config: `~/.config/crush/crushrc`; Windows `%USERPROFILE%/.config/crush/crushrc` (user); `.crushrc` (project).
   Shape: `mcp.summer-engine = { type: "stdio", command, args }`.
-- Skills: `~/.config/crush/skills` (user) or `.crush/skills` (project) as `<skill>/SKILL.md`.
+- Skills: `~/.agents/skills` (user) or `.agents/skills` (project) as `<skill>/SKILL.md`.
 - After: Restart Crush so it reloads crushrc.
 
 Source of truth: `src/installer/agent-table.ts` (one row per agent).

integrations/grok-build/README.md

@@ -6,7 +6,7 @@ is intentionally empty. Support is delivered at install time by
 
 - MCP config: `~/.grok/config.toml`; Windows `%USERPROFILE%/.grok/config.toml` (user); `.grok/config.toml` (project).
   Shape: `[mcp_servers.summer-engine]` table (TOML).
-- Skills: `~/.grok/skills` (user) or `.grok/skills` (project) as `<skill>/SKILL.md`.
+- Skills: `~/.agents/skills` (user) or `.agents/skills` (project) as `<skill>/SKILL.md`.
 - After: Restart Grok Build so it reloads config.toml (it also reads ~/.claude.json and .cursor/mcp.json).
 
 Source of truth: `src/installer/agent-table.ts` (one row per agent).

integrations/hermes/README.md

@@ -6,7 +6,7 @@ is intentionally empty. Support is delivered at install time by
 
 - MCP config: `~/.hermes/config.yaml`; Windows `%USERPROFILE%/.hermes/config.yaml` (user); user scope only (project requests fall back with a warning).
   Shape: `mcp_servers.summer-engine = { command, args }` (YAML).
-- Skills: `~/.hermes/skills` (user) or `.hermes/skills` (project) as `<skill>/SKILL.md`. Project skills need `hermes skills trust` before Hermes loads them.
+- Skills: `~/.hermes/skills` (user) or `.agents/skills` (project) as `<skill>/SKILL.md`. Project skills need `hermes skills trust` before Hermes loads them.
 - After: Run /reload-mcp in Hermes Agent (or restart it).
 
 Source of truth: `src/installer/agent-table.ts` (one row per agent).

integrations/kimi-code/README.md

@@ -6,7 +6,7 @@ is intentionally empty. Support is delivered at install time by
 
 - MCP config: `~/.kimi-code/mcp.json`; Windows `%USERPROFILE%/.kimi-code/mcp.json` (user); `.kimi-code/mcp.json` (project).
   Shape: `mcpServers.summer-engine = { command, args }`.
-- Skills: `~/.kimi-code/skills` (user) or `.kimi-code/skills` (project) as `<skill>/SKILL.md`.
+- Skills: `~/.agents/skills` (user) or `.agents/skills` (project) as `<skill>/SKILL.md`.
 - After: Restart Kimi Code CLI so it reconnects its MCP servers.
 
 Source of truth: `src/installer/agent-table.ts` (one row per agent).

integrations/mistral-vibe/README.md

@@ -6,7 +6,7 @@ is intentionally empty. Support is delivered at install time by
 
 - MCP config: `~/.vibe/config.toml`; Windows `%USERPROFILE%/.vibe/config.toml` (user); `.vibe/config.toml` (project).
   Shape: undefined.
-- Skills: `~/.vibe/skills` (user) or `.vibe/skills` (project) as `<skill>/SKILL.md`.
+- Skills: `~/.vibe/skills` (user) or `.agents/skills` (project) as `<skill>/SKILL.md`.
 - After: Restart Vibe so it reloads config.toml.
 
 Source of truth: `src/installer/agent-table.ts` (one row per agent).

integrations/opencode/README.md

@@ -6,7 +6,7 @@ is intentionally empty. Support is delivered at install time by
 
 - MCP config: `~/.config/opencode/opencode.json`; Windows `%APPDATA%/opencode/opencode.json` (user); `opencode.json` (project).
   Shape: `mcp.summer-engine = { type: "local", command: [npx, ...], enabled: true }`.
-- Skills: `~/.config/opencode/skills` (user) or `.opencode/skills` (project) as `<skill>/SKILL.md`. OpenCode loads skills from this folder on the next session. Summer 3.0 and earlier wrote markdown under agents/summer; `--force` removes those.
+- Skills: `~/.agents/skills` (user) or `.agents/skills` (project) as `<skill>/SKILL.md`. OpenCode loads skills from this folder on the next session. Summer 3.0 wrote markdown under agents/summer and 3.1.0 wrote opencode/skills; `--force` removes both.
 - After: Restart OpenCode so it reloads opencode.json.
 
 Source of truth: `src/installer/agent-table.ts` (one row per agent).

integrations/rovo-dev/README.md

@@ -6,7 +6,7 @@ is intentionally empty. Support is delivered at install time by
 
 - MCP config: `~/.rovodev/mcp.json`; Windows `%USERPROFILE%/.rovodev/mcp.json` (user); user scope only (project requests fall back with a warning).
   Shape: undefined.
-- Skills: `~/.rovodev/skills` (user) or `.rovodev/skills` (project) as `<skill>/SKILL.md`.
+- Skills: `~/.agents/skills` (user) or `.agents/skills` (project) as `<skill>/SKILL.md`.
 - After: Restart Rovo Dev CLI so it reconnects its MCP servers.
 
 Source of truth: `src/installer/agent-table.ts` (one row per agent).

integrations/vscode-copilot/README.md

@@ -6,7 +6,7 @@ is intentionally empty. Support is delivered at install time by
 
 - MCP config: `~/Library/Application Support/Code/User/mcp.json`; Linux `~/.config/Code/User/mcp.json`; Windows `%APPDATA%/Code/User/mcp.json` (user); `.vscode/mcp.json` (project).
   Shape: `servers.summer-engine = { type: "stdio", command, args }`.
-- Skills: `~/.copilot/skills` (user) or `.github/skills` (project) as `<skill>/SKILL.md`.
+- Skills: `~/.agents/skills` (user) or `.agents/skills` (project) as `<skill>/SKILL.md`.
 - After: Restart VS Code or run MCP: List Servers, then start summer-engine in Copilot Agent mode.
 
 Source of truth: `src/installer/agent-table.ts` (one row per agent).

integrations/warp/README.md

@@ -6,7 +6,7 @@ is intentionally empty. Support is delivered at install time by
 
 - MCP config: `~/.warp/.mcp.json`; Windows `%USERPROFILE%/.warp/.mcp.json` (user); `.warp/.mcp.json` (project).
   Shape: `mcpServers.summer-engine = { command, args }`.
-- Skills: `~/.warp/skills` (user) or `.warp/skills` (project) as `<skill>/SKILL.md`.
+- Skills: `~/.agents/skills` (user) or `.agents/skills` (project) as `<skill>/SKILL.md`.
 - After: Warp detects the file and spawns the server; check Settings > AI > MCP servers.
 
 Source of truth: `src/installer/agent-table.ts` (one row per agent).

integrations/windsurf/README.md

@@ -6,7 +6,7 @@ is intentionally empty. Support is delivered at install time by
 
 - MCP config: `~/.codeium/windsurf/mcp_config.json`; Windows `%USERPROFILE%/.codeium/windsurf/mcp_config.json` (user); user scope only (project requests fall back with a warning).
   Shape: `mcpServers.summer-engine = { command, args }`.
-- Skills: `~/.codeium/windsurf/skills` (user) or `.windsurf/skills` (project) as `<skill>/SKILL.md`.
+- Skills: `~/.agents/skills` (user) or `.agents/skills` (project) as `<skill>/SKILL.md`.
 - After: Restart Devin Desktop (formerly Windsurf) and refresh MCP servers from the agent settings. Devin's docs say mcp_config.json configures the Cascade agent; for the Devin agent add the server in the app's MCP settings with the same command.
 
 Source of truth: `src/installer/agent-table.ts` (one row per agent).

src/cli/commands/skills.ts

@@ -31,7 +31,15 @@ import {
 } from "../../installer/skill-locations.js";
 
 import { PACKAGE_ROOT } from "../../core/package-root.js";
-import { agentLabel as tableAgentLabel, agentSpec, defaultPathContext, legacyRuleFiles } from "../../installer/agent-table.js";
+import {
+  agentLabel as tableAgentLabel,
+  agentSpec,
+  agentsSharingSkills,
+  defaultPathContext,
+  isSharedSkillsPath,
+  legacyRuleFiles,
+  legacySkillDirs,
+} from "../../installer/agent-table.js";
 import { TOOLKIT_VERSION as cliVersion } from "../../core/version.js";
 
 // Skill files live in library/skills/<slug>/ and are resolved through the
@@ -288,6 +296,14 @@ function printInstallSummary(
   const reloadHint = agent === "summer" ? undefined : agentSpec(agent).skills?.reloadHint;
   if (location.kind === "skill-dir") {
     console.log(`${label} can read skills from ${tildeified}/<skill>/SKILL.md`);
+    if (isSharedSkillsPath(location.path)) {
+      const others = agentsSharingSkills(scope, defaultPathContext())
+        .map((spec) => spec.label)
+        .filter((name) => name !== label);
+      if (others.length > 0) {
+        console.log(`This is the shared agentskills.io folder; ${others.join(", ")} read it too, so they are covered by this install.`);
+      }
+    }
     if (reloadHint) console.log(reloadHint);
   } else if (location.kind === "cursor-rule-dir") {
     console.log(`Cursor rules are in ${tildeified}/summer-<skill>.mdc`);
@@ -409,12 +425,21 @@ skillsCommand
       // (Cursor, OpenCode): drop the rule files 3.0 wrote so the agent does not
       // load both for the same slug. Only files with Summer's own naming go.
       if (agent !== "summer" && !process.env.SUMMER_SKILLS_DIR) {
-        const legacy = legacyRuleFiles(agentSpec(agent), scope, defaultPathContext(), skills.map((skill) => skill.name)) ?? [];
+        const names = skills.map((skill) => skill.name);
+        const legacy = legacyRuleFiles(agentSpec(agent), scope, defaultPathContext(), names) ?? [];
         for (const file of legacy) {
           if (!existsSync(file)) continue;
           rmSync(file, { force: true });
           console.log(`  Removed ${tildeify(file)} (rule file from Summer 3.0; now a skill)`);
         }
+        // 3.1.0 wrote skills into each agent's own folder; agents that read
+        // the shared ~/.agents/skills now install there. Drop Summer's copies
+        // (dirs with a SKILL.md and a library name) from the old folder.
+        for (const dir of legacySkillDirs(agentSpec(agent), scope, defaultPathContext(), names) ?? []) {
+          if (!existsSync(join(dir, "SKILL.md"))) continue;
+          rmSync(dir, { recursive: true, force: true });
+          console.log(`  Removed ${tildeify(dir)} (moved to the shared skills folder)`);
+        }
       }
     }
     if (name && skills[0]?.status === "preview") {

src/installer/agent-table.test.ts

@@ -11,7 +11,10 @@ import {
   AGENT_IDS,
   agentAliasMap,
   agentSpec,
+  agentsSharingSkills,
   allAgentSpecs,
+  isSharedSkillsPath,
+  legacySkillDirs,
   resolveMcpPath,
   resolveSkillPath,
   skillCapableAgents,
@@ -128,13 +131,35 @@ describe("agent table paths", () => {
     );
   });
 
-  it("Cursor and Devin Desktop now get SKILL.md skills, not rule files", () => {
-    expect(resolveSkillPath(agentSpec("cursor"), "user", ctx("darwin"))).toEqual({
-      kind: "skill-dir",
-      path: "/home/dev/.cursor/skills",
-      scope: "user",
-    });
-    expect(resolveSkillPath(agentSpec("windsurf"), "user", ctx("darwin"))?.path).toBe("/home/dev/.codeium/windsurf/skills");
+  it("agents whose docs read the agentskills.io folder all install to ~/.agents/skills", () => {
+    const shared = agentsSharingSkills("user", ctx("darwin")).map((s) => s.id).sort();
+    expect(shared).toEqual([
+      "amp", "codex", "crush", "cursor", "factory", "grok-build", "kimi-code", "opencode",
+      "rovo-dev", "vscode-copilot", "warp", "windsurf", "zed",
+    ]);
+    for (const id of shared) {
+      expect(resolveSkillPath(agentSpec(id), "user", ctx("darwin"))?.path).toBe("/home/dev/.agents/skills");
+    }
+    // Project scope adds the agents that only read .agents/skills inside a repo.
+    const project = agentsSharingSkills("project", ctx("darwin")).map((s) => s.id);
+    for (const id of ["antigravity", "goose", "hermes", "mistral-vibe"]) expect(project).toContain(id);
+    // Native-only agents stay where their docs say.
+    expect(resolveSkillPath(agentSpec("claude-code"), "user", ctx("darwin"))?.path).toBe("/home/dev/.claude/skills");
+    expect(resolveSkillPath(agentSpec("github-copilot"), "user", ctx("darwin"))?.path).toBe("/home/dev/.copilot/skills");
+    expect(isSharedSkillsPath("/home/dev/.agents/skills")).toBe(true);
+    expect(isSharedSkillsPath("/home/dev/.claude/skills")).toBe(false);
+  });
+
+  it("legacySkillDirs names the 3.1.0 native folders for moved agents and nothing for agents that never moved", () => {
+    expect(legacySkillDirs(agentSpec("cursor"), "user", ctx("darwin"), ["debug", "play"])).toEqual([
+      "/home/dev/.cursor/skills/debug",
+      "/home/dev/.cursor/skills/play",
+    ]);
+    expect(legacySkillDirs(agentSpec("amp"), "project", ctx("darwin"), ["debug"])).toEqual([]);
+    expect(legacySkillDirs(agentSpec("claude-code"), "user", ctx("darwin"), ["debug"])).toBeNull();
+    // Hermes only moved at project scope; its user folder is still current.
+    expect(legacySkillDirs(agentSpec("hermes"), "user", ctx("darwin"), ["debug"])).toEqual([]);
+    expect(legacySkillDirs(agentSpec("hermes"), "project", ctx("darwin"), ["debug"])).toEqual(["/work/game/.hermes/skills/debug"]);
   });
 });