The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
docs: shift repo guidance to skills-first workflows
Affaan Mustafaf3db349984b0
diff --git a/.agents/skills/everything-claude-code/SKILL.md b/.agents/skills/everything-claude-code/SKILL.mdindex 799c37f5e..173826a88 100644--- 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.mdOptionally 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 Countsdiff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.jsonindex 397d788b3..abde09a55 100644--- 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": "[email protected]"@@ -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",diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex a68b198b0..1bfa40ee4 100644--- 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"diff --git a/AGENTS.md b/AGENTS.mdindex d92bde107..e2a98807f 100644--- 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 file5. **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 configurationstests/ — Test suite```+`commands/` remains in the repo for compatibility, but the long-term direction is skills-first.+## Success Metrics- All tests pass with 80%+ coveragediff --git a/README.md b/README.mdindex 3f3f548cc..5a6aaf048 100644--- 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 onlycp -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 ||---------|-------------|diff --git a/WORKING-CONTEXT.md b/WORKING-CONTEXT.mdindex 0a21c9976..bda47eeba 100644--- 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.diff --git a/package.json b/package.jsonindex 9150536b5..4cecf1a4a 100644--- 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",diff --git a/scripts/ci/catalog.js b/scripts/ci/catalog.jsindex 46d629768..da08d9ef9 100644--- 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(diff --git a/skills/configure-ecc/SKILL.md b/skills/configure-ecc/SKILL.mdindex 07109a30e..9521dd7da 100644--- 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 |diff --git a/tests/ci/validators.test.js b/tests/ci/validators.test.jsindex b48a4ca31..1b02c41e5 100644--- 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');diff --git a/the-shortform-guide.md b/the-shortform-guide.mdindex 304b0d2d2..c8b412aad 100644--- 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.*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 patternscoding-standards.md # Language best practices- tdd-workflow/ # Multi-file skill with README.md+ tdd-workflow/ # Multi-file skill with SKILL.mdsecurity-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```---