Skip to content

armgit / ECC

Public Imported from GitHub
0

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.md
index 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.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 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.json
index 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.md
index 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 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
diff --git a/README.md b/README.md
index 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 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 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.json
index 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.js
index 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.md
index 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.js
index 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.md
index 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.
![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
```
---