docs: shift repo guidance to skills-first workflows

2026-04-01 22:53:27 +08:00 · 2026-04-01 02:11:24 -07:00
parent 5194d2000a
commit f3db349984
11 changed files with 56 additions and 37 deletions
--- a/.agents/skills/everything-claude-code/SKILL.md
+++ b/.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
-2. Optionally add or update a backing skill under skills/{skill-name}/SKILL.md
+1. Create or update the canonical workflow 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
-Optionally add or update a backing skill under skills/{skill-name}/SKILL.md
+Create or update the canonical skill under skills/{skill-name}/SKILL.md
+Only if needed, add or update commands/{command-name}.md as a compatibility shim
 ```

 ### Sync Catalog Counts
--- a/.claude-plugin/marketplace.json
+++ b/.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",
--- a/.claude-plugin/plugin.json
+++ b/.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"
--- a/AGENTS.md
+++ b/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
--- a/README.md
+++ b/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
-cp everything-claude-code/commands/*.md ~/.claude/commands/
-
-# Copy skills (core vs niche)
+# Copy skills first (primary workflow surface)
 # 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 |
 |---------|-------------|
--- a/WORKING-CONTEXT.md
+++ b/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.
--- a/package.json
+++ b/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",
--- a/scripts/ci/catalog.js
+++ b/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,
-    (_, prefix, __, agentsSuffix, ___, skillsSuffix, ____, commandsSuffix) =>
-      `${prefix}${catalog.agents.count}${agentsSuffix}${catalog.skills.count}${skillsSuffix}${catalog.commands.count}${commandsSuffix}`,
+    /(access to\s+)(\d+)(\s+agents,\s+)(\d+)(\s+skills,\s+and\s+)(\d+)(\s+(?:commands|legacy command shims?))/i,
+    (_, prefix, __, agentsSuffix, ___, skillsSuffix) =>
+      `${prefix}${catalog.agents.count}${agentsSuffix}${catalog.skills.count}${skillsSuffix}${catalog.commands.count} legacy command shims`,
    'README.md quick-start summary'
  );
  nextContent = replaceOrThrow(
--- a/skills/configure-ecc/SKILL.md
+++ b/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 |
--- a/tests/ci/validators.test.js
+++ b/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');
--- a/the-shortform-guide.md
+++ b/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
- **Commands**: `~/.claude/commands/` - quick executable prompts
+- **Skills**: `~/.claude/skills/` - canonical workflow definitions
+- **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
 ```

 ---