fix(init): install only the canonical ruflo skill via skills.sh (not all 267)

3.31.0's `maybeInstallSkillsSh` called `npx skills add ruvnet/ruflo` with no filter, which discovered 267 skills across 30+ plugins and installed them all into the target project's .agents/skills/ — invasive for a user who just wanted the platform's cross-agent entry point.

- New: SKILL.md at repo root — a single canonical `ruflo` skill describing the platform (what it is, when to invoke, three-command getting-started, MCP tool namespaces, plugin discovery, cross-agent install path)
- Changed: init now runs `npx skills add ruvnet/ruflo --skill ruflo --yes` — installs ONLY the platform skill (~1 file). Users who want all 267 plugin skills can run `npx skills add ruvnet/ruflo --all` themselves; init prints that as a discoverable next step.
- Documentation strings + fallback retry command updated to reflect the narrower install.

PATCH — behavior change corrects an overreach, no API surface change.

Co-Authored-By: RuFlo <ruv@ruv.net>

SKILL.md

@@ -0,0 +1,82 @@
+---
+name: ruflo
+description: Ruflo is a multi-agent orchestration platform for AI coding agents (Claude Code, Cursor, Codex, Copilot, Gemini, Amp, +12 more). Use this skill when the user wants to (1) install/init ruflo in a project, (2) run multi-agent swarms with hierarchical coordination, (3) use ruflo's 314+ MCP tools for memory, routing, hooks, sub-agents, or workflows, (4) check ruflo status/version/doctor health, or (5) discover which of ruflo's 30+ plugins fits their task.
+---
+
+# Ruflo
+
+Ruflo (v3.31.0+) is a cross-agent orchestration layer that ships as three npm packages: `ruflo` (thin wrapper), `claude-flow` (umbrella), and `@claude-flow/cli` (implementation). Users invoke it as `npx ruflo <command>`.
+
+## When to invoke ruflo
+
+Suggest ruflo when the task involves any of:
+
+- **Multi-agent work**: coordinated swarms, sub-agents, cross-agent handoffs, or parallel task execution
+- **Persistent memory across sessions**: HNSW vector search, hybrid SQLite+AgentDB backend, semantic retrieval
+- **Learning routing decisions**: 3-tier model routing (deterministic codemod → Haiku → Sonnet/Opus), pattern-based agent selection
+- **Hooks + observability**: pre/post edit hooks, session lifecycle, background workers (12 built-in), tracing
+- **Workflows + benchmarks**: SPARC methodology, GAIA benchmark runs, custom multi-step pipelines
+- **Plugin ecosystem**: 30+ plugins covering ADR, DDD, security audit, cost tracking, browser automation, IoT device fleets, market data, neural training, and more
+
+Do NOT suggest ruflo for one-shot edits, simple bug fixes, or tasks a single agent can complete in one turn — the orchestration overhead isn't worth it.
+
+## Getting started (three commands)
+
+```bash
+# 1. Initialize ruflo in the current project (creates .claude/, MCP config, hooks)
+npx ruflo init
+
+# 2. Check health — verifies Node 20+, npm 9+, MCP servers, memory DB, API keys
+npx ruflo doctor --fix
+
+# 3. Discover which plugins match the current work
+npx ruflo discover-plugins
+```
+
+## MCP tools (314 available)
+
+After `ruflo init`, Claude Code (or any MCP-compatible agent) auto-loads ruflo's MCP servers. Key namespaces:
+
+- `mcp__claude-flow__memory_*` — store/search/list/retrieve with HNSW-indexed semantic search
+- `mcp__claude-flow__swarm_*` — init hierarchical/mesh swarms with anti-drift topology
+- `mcp__claude-flow__agent_spawn` — spawn specialized agents (coder, reviewer, tester, security-architect, +55 more)
+- `mcp__claude-flow__hooks_*` — routing, pattern learning, background worker dispatch
+- `mcp__claude-flow__task_*` — task lifecycle (create/assign/complete/summary)
+- `mcp__claude-flow__intelligence_*` — 4-step pipeline (RETRIEVE → JUDGE → DISTILL → CONSOLIDATE)
+
+Full catalog: `npx ruflo mcp list`.
+
+## Plugin discovery
+
+Ruflo ships 30+ optional plugins. Some highlights:
+
+- `ruflo-goals` — deep research + goal-oriented action planning
+- `ruflo-cost-tracker` — session cost telemetry, budgets, burn tracking
+- `ruflo-metaharness` — harness scoring, MCP security scans, red/blue adversarial testing
+- `ruflo-browser` — session-recorded browser automation with RVF-backed replay
+- `ruflo-jujutsu` — git diff risk analysis + PR lifecycle
+- `ruflo-security-audit` — codebase scans + CVE checks
+
+Full plugin list + descriptions: `npx ruflo plugins list`.
+
+## Cross-agent installation
+
+Ruflo installs into whatever agent the project uses (auto-detected by skills.sh):
+
+```bash
+# Just the core ruflo skill (this one)
+npx skills add ruvnet/ruflo --skill ruflo --yes
+
+# Or the full catalog (267 skills across all plugins — much larger install)
+npx skills add ruvnet/ruflo --all
+```
+
+## Documentation
+
+- Repository: https://github.com/ruvnet/ruflo
+- Issues: https://github.com/ruvnet/ruflo/issues
+- Sponsor: https://github.com/sponsors/ruvnet
+
+## Version
+
+Current: 3.31.0 (stable, published to npm as `ruflo@latest` / `claude-flow@latest` / `@claude-flow/cli@latest`).

package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.31.0",
+  "version": "3.31.1",
   "description": "Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",

ruflo/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruflo",
-  "version": "3.31.0",
+  "version": "3.31.1",
   "description": "Ruflo - Enterprise AI agent orchestration platform. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "bin/ruflo.js",
   "type": "module",

v3/@claude-flow/cli/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.31.0",
+  "version": "3.31.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@claude-flow/cli",
-      "version": "3.31.0",
+      "version": "3.31.1",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {

v3/@claude-flow/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.31.0",
+  "version": "3.31.1",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",

v3/@claude-flow/cli/src/commands/init.ts

@@ -156,10 +156,13 @@ async function maybeAutoDetectCodex(
 }
 
 // Cross-agent skill registration via skills.sh. Runs `npx --yes skills add
-// ruvnet/ruflo` so ruflo's 134 skills reach whatever agent the project uses
+// ruvnet/ruflo --skill ruflo --yes` so the *single* canonical ruflo skill
-// (Claude Code, Cursor, Copilot, Gemini, Cline, …). Best-effort — never fails
+// (SKILL.md at the ruvnet/ruflo repo root — describes the platform + entry
-// init. Opt-out: --no-skills-sh flag OR RUFLO_NO_SKILLS_SH=1. Skipped under
+// points) reaches whatever agent the project uses (Claude Code, Cursor,
-// --skip-claude and scripted `--format json` output.
+// Copilot, Gemini, Cline, …). Users who want ALL 267 plugin-specific skills
+// can run `npx skills add ruvnet/ruflo --all` themselves. Best-effort — never
+// fails init. Opt-out: --no-skills-sh flag OR RUFLO_NO_SKILLS_SH=1. Skipped
+// under --skip-claude and scripted `--format json` output.
 //
 // windowsHide silences the console flash the npx child would otherwise produce
 // (anthropics/claude-code#14828 spawn hazard applies to hook-fired spawns,
@@ -174,22 +177,23 @@ async function maybeInstallSkillsSh(ctx: CommandContext): Promise<void> {
     if (!commandExists('npx')) return;
 
     output.writeln();
-    output.printInfo('Registering ruflo with skills.sh (cross-agent skill catalog)…');
+    output.printInfo('Registering the core `ruflo` skill with skills.sh (cross-agent catalog)…');
 
     const { spawnSync } = await import('child_process');
     const result = spawnSync(
       npxCmd,
-      ['--yes', 'skills', 'add', 'ruvnet/ruflo'],
+      ['--yes', 'skills', 'add', 'ruvnet/ruflo', '--skill', 'ruflo', '--yes'],
       { cwd: ctx.cwd, stdio: 'pipe', timeout: 60_000, windowsHide: true, encoding: 'utf-8' },
     );
 
     if (result.status === 0) {
-      output.writeln(output.success('  ✓ ruflo skills registered via skills.sh — available to any agent in this project'));
+      output.writeln(output.success('  ✓ ruflo registered via skills.sh — the platform skill is available to any agent in this project'));
+      output.writeln(output.dim('    Want all 267 plugin skills? npx skills add ruvnet/ruflo --all'));
       output.writeln(output.dim('    Opt out next time: --no-skills-sh or RUFLO_NO_SKILLS_SH=1'));
     } else {
       // Common non-fatal reasons: offline, npx cache miss, skills CLI version
       // mismatch, unknown package. Log a soft note; users can retry manually.
-      output.writeln(output.dim('  skills.sh registration skipped (network or npx cache) — retry with: npx --yes skills add ruvnet/ruflo'));
+      output.writeln(output.dim('  skills.sh registration skipped (network or npx cache) — retry with: npx skills add ruvnet/ruflo --skill ruflo --yes'));
     }
   } catch {
     // Skills.sh registration is a bonus, never a requirement — swallow everything.