docs: shift repo guidance to skills-first workflows

.agents/skills/everything-claude-code/SKILL.md

@@ -304,24 +304,24 @@ Register the agent in AGENTS.md
 Optionally update README.md and docs/COMMAND-AGENT-MAP.md
 ```
 
-### Add New Command
+### Add New Workflow Surface
 
-Adds a new command to the system, often paired with a backing skill.
+Adds or updates a workflow entrypoint. Default to skills-first; only add a command shim when legacy slash compatibility is still required.
 
 **Frequency**: ~1 times per month
 
 **Steps**:
-1. Create a new markdown file under commands/{command-name}.md
+1. Create or update the canonical workflow under skills/{skill-name}/SKILL.md
-2. Optionally add or update a backing skill under skills/{skill-name}/SKILL.md
+2. Only if needed, add or update commands/{command-name}.md as a compatibility shim
 
 **Files typically involved**:
-- `commands/*.md`
 - `skills/*/SKILL.md`
+- `commands/*.md` (only when a legacy shim is intentionally retained)
 
 **Example commit sequence**:
 ```
-Create a new markdown file under commands/{command-name}.md
+Create or update the canonical skill under skills/{skill-name}/SKILL.md
-Optionally add or update a backing skill under skills/{skill-name}/SKILL.md
+Only if needed, add or update commands/{command-name}.md as a compatibility shim
 ```
 
 ### Sync Catalog Counts

.claude-plugin/marketplace.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "everything-claude-code",
-  "description": "Battle-tested Claude Code configurations from an Anthropic hackathon winner — agents, skills, hooks, commands, and rules evolved over 10+ months of intensive daily use",
+  "description": "Battle-tested Claude Code configurations from an Anthropic hackathon winner — agents, skills, hooks, rules, and legacy command shims evolved over 10+ months of intensive daily use",
   "owner": {
     "name": "Affaan Mustafa",
     "email": "me@affaanmustafa.com"
@@ -13,7 +13,7 @@
     {
       "name": "everything-claude-code",
       "source": "./",
-      "description": "The most comprehensive Claude Code plugin — 14+ agents, 56+ skills, 33+ commands, and production-ready hooks for TDD, security scanning, code review, and continuous learning",
+      "description": "The most comprehensive Claude Code plugin — 36 agents, 142 skills, 68 legacy command shims, and production-ready hooks for TDD, security scanning, code review, and continuous learning",
       "version": "1.9.0",
       "author": {
         "name": "Affaan Mustafa",

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "everything-claude-code",
   "version": "1.9.0",
-  "description": "Complete collection of battle-tested Claude Code configs from an Anthropic hackathon winner - agents, skills, hooks, and rules evolved over 10+ months of intensive daily use",
+  "description": "Complete collection of battle-tested Claude Code configs from an Anthropic hackathon winner - agents, skills, hooks, rules, and legacy command shims evolved over 10+ months of intensive daily use",
   "author": {
     "name": "Affaan Mustafa",
     "url": "https://x.com/affaanmustafa"

AGENTS.md

@@ -116,6 +116,12 @@ Troubleshoot failures: check test isolation → verify mocks → fix implementat
    - If there is no obvious project doc location, ask before creating a new top-level file
 5. **Commit** — Conventional commits format, comprehensive PR summaries
 
+## Workflow Surface Policy
+
+- `skills/` is the canonical workflow surface.
+- New workflow contributions should land in `skills/` first.
+- `commands/` is a legacy slash-entry compatibility surface and should only be added or updated when a shim is still required for migration or cross-harness parity.
+
 ## Git Workflow
 
 **Commit format:** `<type>: <description>` — Types: feat, fix, refactor, docs, test, chore, perf, ci
@@ -149,6 +155,8 @@ mcp-configs/     — 14 MCP server configurations
 tests/           — Test suite
 ```
 
+`commands/` remains in the repo for compatibility, but the long-term direction is skills-first.
+
 ## Success Metrics
 
 - All tests pass with 80%+ coverage

README.md

@@ -34,7 +34,7 @@
 
 **The performance optimization system for AI agent harnesses. From an Anthropic hackathon winner.**
 
-Not just configs. A complete system: skills, instincts, memory optimization, continuous learning, security scanning, and research-first development. Production-ready agents, hooks, commands, rules, and MCP configurations evolved over 10+ months of intensive daily use building real products.
+Not just configs. A complete system: skills, instincts, memory optimization, continuous learning, security scanning, and research-first development. Production-ready agents, skills, hooks, rules, MCP configurations, and legacy command shims evolved over 10+ months of intensive daily use building real products.
 
 Works across **Claude Code**, **Codex**, **Cowork**, and other AI agent harnesses.
 
@@ -212,17 +212,20 @@ For manual install instructions see the README in the `rules/` folder. When copy
 ### Step 3: Start Using
 
 ```bash
-# Try a command (plugin install uses namespaced form)
+# Skills are the primary workflow surface.
+# Existing slash-style command names still work while ECC migrates off commands/.
+
+# Plugin install uses the namespaced form
 /everything-claude-code:plan "Add user authentication"
 
-# Manual install (Option 2) uses the shorter form:
+# Manual install keeps the shorter slash form:
 # /plan "Add user authentication"
 
 # Check available commands
 /plugin list everything-claude-code@everything-claude-code
 ```
 
-**That's it!** You now have access to 36 agents, 142 skills, and 68 commands.
+**That's it!** You now have access to 36 agents, 142 skills, and 68 legacy command shims.
 
 ### Multi-model commands require additional setup
 
@@ -392,7 +395,7 @@ everything-claude-code/
 |   |-- autonomous-loops/           # Autonomous loop patterns: sequential pipelines, PR loops, DAG orchestration (NEW)
 |   |-- plankton-code-quality/      # Write-time code quality enforcement with Plankton hooks (NEW)
 |
-|-- commands/         # Slash commands for quick execution
+|-- commands/         # Legacy slash-entry shims; prefer skills/
 |   |-- tdd.md              # /tdd - Test-driven development
 |   |-- plan.md             # /plan - Implementation planning
 |   |-- e2e.md              # /e2e - E2E test generation
@@ -671,10 +674,7 @@ cp -r everything-claude-code/rules/python ~/.claude/rules/
 cp -r everything-claude-code/rules/golang ~/.claude/rules/
 cp -r everything-claude-code/rules/php ~/.claude/rules/
 
-# Copy commands
+# Copy skills first (primary workflow surface)
-cp everything-claude-code/commands/*.md ~/.claude/commands/
-
-# Copy skills (core vs niche)
 # Recommended (new users): core/general skills only
 cp -r everything-claude-code/.agents/skills/* ~/.claude/skills/
 cp -r everything-claude-code/skills/search-first ~/.claude/skills/
@@ -683,6 +683,10 @@ cp -r everything-claude-code/skills/search-first ~/.claude/skills/
 # for s in django-patterns django-tdd laravel-patterns springboot-patterns; do
 # cp -r everything-claude-code/skills/$s ~/.claude/skills/
 # done
+
+# Optional: keep legacy slash-command compatibility during migration
+mkdir -p ~/.claude/commands
+cp everything-claude-code/commands/*.md ~/.claude/commands/
 ```
 
 #### Add hooks to settings.json
@@ -691,7 +695,7 @@ Copy the hooks from `hooks/hooks.json` to your `~/.claude/settings.json`.
 
 #### Configure MCPs
 
-Copy desired MCP servers from `mcp-configs/mcp-servers.json` to your `~/.claude.json`.
+Copy desired MCP server definitions from `mcp-configs/mcp-servers.json` into your official Claude Code config in `~/.claude/settings.json`, or into a project-scoped `.mcp.json` if you want repo-local MCP access.
 
 **Important:** Replace `YOUR_*_HERE` placeholders with your actual API keys.
 
@@ -716,7 +720,7 @@ You are a senior code reviewer...
 
 ### Skills
 
-Skills are workflow definitions invoked by commands or agents:
+Skills are the primary workflow surface. They can be invoked directly, suggested automatically, and reused by agents. ECC still ships `commands/` during migration, but new workflow development should land in `skills/` first.
 
 ```markdown
 # TDD Workflow
@@ -762,7 +766,7 @@ See [`rules/README.md`](rules/README.md) for installation and structure details.
 
 ## Which Agent Should I Use?
 
-Not sure where to start? Use this quick reference:
+Not sure where to start? Use this quick reference. Skills are the canonical workflow surface; slash entries below are the compatibility form most users already know.
 
 | I want to... | Use this command | Agent used |
 |--------------|-----------------|------------|
@@ -782,6 +786,8 @@ Not sure where to start? Use this quick reference:
 
 ### Common Workflows
 
+Slash forms below are shown because they are still the fastest familiar entrypoint. Under the hood, ECC is shifting these workflows toward skills-first definitions.
+
 **Starting a new feature:**
 ```
 /everything-claude-code:plan "Add user authentication with OAuth"
@@ -1134,7 +1140,7 @@ OpenCode's plugin system is MORE sophisticated than Claude Code with 20+ event t
 
 **Additional OpenCode events**: `file.edited`, `file.watcher.updated`, `message.updated`, `lsp.client.diagnostics`, `tui.toast.show`, and more.
 
-### Available Commands (31+)
+### Available Slash Entry Shims (31+)
 
 | Command | Description |
 |---------|-------------|

WORKING-CONTEXT.md

@@ -34,6 +34,7 @@ Public ECC plugin repo for agents, skills, commands, hooks, rules, install surfa
   - rewrite content-facing skills to use source-backed voice modeling
   - remove generic LLM rhetoric, canned CTA patterns, and forced platform stereotypes
   - continue one-by-one audit of overlapping or low-signal skill content
+  - move repo guidance and contribution flow to skills-first, leaving commands only as explicit compatibility shims
 - Security:
   - keep dependency posture clean
   - preserve self-contained hook and MCP behavior
@@ -65,6 +66,7 @@ Public ECC plugin repo for agents, skills, commands, hooks, rules, install surfa
   - `ECC-206` ecosystem CI baseline
   - `ECC-207` PR backlog audit and merge-policy enforcement
   - `ECC-208` context hygiene
+  - `ECC-210` skills-first workflow migration and command compatibility retirement
 
 ## Update Rule
 
@@ -84,3 +86,4 @@ Keep this file detailed for only the current sprint, blockers, and next actions.
 - 2026-04-01: The remaining self-contained piece of `#834`, `docs/zh-CN/skills/browser-qa/SKILL.md`, was ported directly into the repo. After commit, `#834` should be closed as superseded-by-direct-port.
 - 2026-04-01: Content skill cleanup started with `content-engine`, `crosspost`, `article-writing`, and `investor-outreach`. The new direction is source-first voice capture, explicit anti-trope bans, and no forced platform persona shifts.
 - 2026-04-01: `node scripts/ci/check-unicode-safety.js --write` sanitized the remaining emoji-bearing Markdown files, including several `remotion-video-creation` rule docs and an old local plan note.
+- 2026-04-01: Core English repo surfaces were shifted to a skills-first posture. README, AGENTS, plugin metadata, and contributor instructions now treat `skills/` as canonical and `commands/` as legacy slash-entry compatibility during migration.

package.json

@@ -1,7 +1,7 @@
 {
   "name": "ecc-universal",
   "version": "1.9.0",
-  "description": "Complete collection of battle-tested Claude Code configs — agents, skills, hooks, commands, and rules evolved over 10+ months of intensive daily use by an Anthropic hackathon winner",
+  "description": "Complete collection of battle-tested Claude Code configs — agents, skills, hooks, rules, and legacy command shims evolved over 10+ months of intensive daily use by an Anthropic hackathon winner",
   "keywords": [
     "claude-code",
     "ai",

scripts/ci/catalog.js

@@ -86,7 +86,9 @@ function replaceOrThrow(content, regex, replacer, source) {
 function parseReadmeExpectations(readmeContent) {
   const expectations = [];
 
-  const quickStartMatch = readmeContent.match(/access to\s+(\d+)\s+agents,\s+(\d+)\s+skills,\s+and\s+(\d+)\s+commands/i);
+  const quickStartMatch = readmeContent.match(
+    /access to\s+(\d+)\s+agents,\s+(\d+)\s+skills,\s+and\s+(\d+)\s+(?:commands|legacy command shims?)/i
+  );
   if (!quickStartMatch) {
     throw new Error('README.md is missing the quick-start catalog summary');
   }
@@ -369,9 +371,9 @@ function syncEnglishReadme(content, catalog) {
 
   nextContent = replaceOrThrow(
     nextContent,
-    /(access to\s+)(\d+)(\s+agents,\s+)(\d+)(\s+skills,\s+and\s+)(\d+)(\s+commands)/i,
+    /(access to\s+)(\d+)(\s+agents,\s+)(\d+)(\s+skills,\s+and\s+)(\d+)(\s+(?:commands|legacy command shims?))/i,
-    (_, prefix, __, agentsSuffix, ___, skillsSuffix, ____, commandsSuffix) =>
+    (_, prefix, __, agentsSuffix, ___, skillsSuffix) =>
-      `${prefix}${catalog.agents.count}${agentsSuffix}${catalog.skills.count}${skillsSuffix}${catalog.commands.count}${commandsSuffix}`,
+      `${prefix}${catalog.agents.count}${agentsSuffix}${catalog.skills.count}${skillsSuffix}${catalog.commands.count} legacy command shims`,
     'README.md quick-start summary'
   );
   nextContent = replaceOrThrow(

skills/configure-ecc/SKILL.md

@@ -140,7 +140,7 @@ For each selected category, print the full list of skills below and ask the user
 | Skill | Description |
 |-------|-------------|
 | `continuous-learning` | Auto-extract reusable patterns from sessions as learned skills |
-| `continuous-learning-v2` | Instinct-based learning with confidence scoring, evolves into skills/commands/agents |
+| `continuous-learning-v2` | Instinct-based learning with confidence scoring, evolves into skills, agents, and optional legacy command shims |
 | `eval-harness` | Formal evaluation framework for eval-driven development (EDD) |
 | `iterative-retrieval` | Progressive context refinement for subagent context problem |
 | `security-review` | Security checklist: auth, input, secrets, API, payment features |

tests/ci/validators.test.js

@@ -514,7 +514,7 @@ function runTests() {
     const zhDocsReadme = fs.readFileSync(zhDocsReadmePath, 'utf8');
     const zhAgentsDoc = fs.readFileSync(zhAgentsPath, 'utf8');
 
-    assert.ok(readme.includes('Access to 1 agents, 1 skills, and 1 commands.'), 'Should sync README quick-start summary');
+    assert.ok(readme.includes('Access to 1 agents, 1 skills, and 1 legacy command shims'), 'Should sync README quick-start summary');
     assert.ok(readme.includes('| Agents | PASS: 1 agents |'), 'Should sync README comparison table');
     assert.ok(readme.includes('| Skills | 16 | .agents/skills/ |'), 'Should not rewrite unrelated README tables');
     assert.ok(readme.includes('| **Agents** | 1 | Shared (AGENTS.md) | Shared (AGENTS.md) | 12 |'), 'Should sync README parity table');

the-shortform-guide.md

@@ -12,24 +12,24 @@ Here's my complete setup after 10 months of daily use: skills, hooks, subagents,
 
 ## Skills and Commands
 
-Skills operate like rules, constricted to certain scopes and workflows. They're shorthand to prompts when you need to execute a particular workflow.
+Skills are the primary workflow surface. They act like scoped workflow bundles: reusable prompts, structure, supporting files, and codemaps when you need a particular execution pattern.
 
-After a long session of coding with Opus 4.5, you want to clean out dead code and loose .md files? Run `/refactor-clean`. Need testing? `/tdd`, `/e2e`, `/test-coverage`. Skills can also include codemaps - a way for Claude to quickly navigate your codebase without burning context on exploration.
+After a long session of coding with Opus 4.5, you want to clean out dead code and loose .md files? Run `/refactor-clean`. Need testing? `/tdd`, `/e2e`, `/test-coverage`. Those slash entries are convenient, but the real durable unit is the underlying skill. Skills can also include codemaps - a way for Claude to quickly navigate your codebase without burning context on exploration.
 
 ![Terminal showing chained commands](./assets/images/shortform/02-chaining-commands.jpeg)
 *Chaining commands together*
 
-Commands are skills executed via slash commands. They overlap but are stored differently:
+ECC still ships a `commands/` layer, but it is best thought of as legacy slash-entry compatibility during migration. The durable logic should live in skills.
 
-- **Skills**: `~/.claude/skills/` - broader workflow definitions
+- **Skills**: `~/.claude/skills/` - canonical workflow definitions
-- **Commands**: `~/.claude/commands/` - quick executable prompts
+- **Commands**: `~/.claude/commands/` - legacy slash-entry shims when you still need them
 
 ```bash
 # Example skill structure
 ~/.claude/skills/
   pmx-guidelines.md      # Project-specific patterns
   coding-standards.md    # Language best practices
-  tdd-workflow/          # Multi-file skill with README.md
+  tdd-workflow/          # Multi-file skill with SKILL.md
   security-review/       # Checklist-based skill
 ```
 
@@ -149,7 +149,7 @@ Your 200k context window before compacting might only be 70k with too many tools
 # Check enabled MCPs
 /mcp
 
-# Disable unused ones in ~/.claude.json under projects.disabledMcpServers
+# Disable unused ones in ~/.claude/settings.json or in the current repo's .mcp.json
 ```
 
 ---