From f3db349984b0b611fc144dfd4dd20230cd2cb9a5 Mon Sep 17 00:00:00 2001 From: Affaan Mustafa Date: Wed, 1 Apr 2026 02:11:24 -0700 Subject: [PATCH] docs: shift repo guidance to skills-first workflows --- .../skills/everything-claude-code/SKILL.md | 14 ++++---- .claude-plugin/marketplace.json | 4 +-- .claude-plugin/plugin.json | 2 +- AGENTS.md | 8 +++++ README.md | 32 +++++++++++-------- WORKING-CONTEXT.md | 3 ++ package.json | 2 +- scripts/ci/catalog.js | 10 +++--- skills/configure-ecc/SKILL.md | 2 +- tests/ci/validators.test.js | 2 +- the-shortform-guide.md | 14 ++++---- 11 files changed, 56 insertions(+), 37 deletions(-) diff --git a/.agents/skills/everything-claude-code/SKILL.md b/.agents/skills/everything-claude-code/SKILL.md index 799c37f5..173826a8 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.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 diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 397d788b..abde09a5 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": "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", diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index a68b198b..1bfa40ee 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.md index d92bde10..e2a98807 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 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:** `: ` — 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 diff --git a/README.md b/README.md index 3f3f548c..5a6aaf04 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 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 | |---------|-------------| diff --git a/WORKING-CONTEXT.md b/WORKING-CONTEXT.md index 0a21c997..bda47eeb 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.json index 9150536b..4cecf1a4 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.js index 46d62976..da08d9ef 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.md index 07109a30..9521dd7d 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.js index b48a4ca3..1b02c41e 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.md index 304b0d2d..c8b412aa 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. ![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 ``` ---