Ecc Guide

ecc Guide

Use this skill when a user needs help understanding, navigating, installing, or choosing parts of Everything OpenAI Codex.

When To Use

Use this skill when the user:

• asks what ecc includes
• wants help finding a skill, command, agent, hook, rule, or install profile
• is new to the repository and needs a guided path
• asks "how do I do X with ecc?"
• asks which ecc components fit a project
• needs a lightweight explanation of how commands, skills, agents, hooks, and rules relate
• is confused by install paths, duplicate installs, reset/uninstall, or selective install options

Core Principle

Answer from current files, not memory. ecc changes quickly, so hard-coded catalog counts, feature lists, and install instructions go stale.

When the ecc repository is available, inspect the relevant files before giving a concrete answer:

node scripts/ci/catalog.js --json
find skills -maxdepth 2 -name SKILL.md | sort
find commands -maxdepth 1 -name '*.md' | sort
find agents -maxdepth 1 -name '*.md' | sort
node scripts/install-plan.js --list-profiles
node scripts/install-plan.js --list-components --json

Use the smallest set of reads needed for the user's question.

Repository Map

• README.md: install paths, uninstall/reset guidance, public positioning, FAQs
• AGENTS.md: contributor guidance and project structure
• agent.yaml: exported gitagent surface and command list
• commands/: maintained slash-command compatibility shims
• skills/*/SKILL.md: reusable workflows and domain playbooks
• agents/*.md: delegated subagent role prompts
• rules/: language and harness rules
• hooks/README.md, hooks/hooks.json, scripts/hooks/: hook behavior and safety gates
• manifests/install-*.json: selective install modules, components, profiles, and target support
• docs/: harness guides, architecture notes, translated docs, release docs

Response Style

Lead with the answer, then give the next action. Most users do not need a full catalog dump.

Good first response shape:

1. what to use
2. why it fits
3. exact file or command to inspect
4. one next command or question

Avoid:

• listing every skill or command by default
• repeating large README sections
• recommending retired command shims when a skill-first path exists
• claiming a component exists without checking the filesystem
• replacing install guidance with manual copy commands when the managed installer supports the target

Common Tasks

New User Onboarding

Give a short menu:

• install or reset ecc
• pick skills for a project
• understand commands vs skills
• inspect hooks and safety behavior
• run a harness audit
• find a specific workflow

Point to README.md for install/reset and /project-init for project-specific onboarding.

Feature Discovery

For "what should I use for X?":

1. Search skills/, commands/, and agents/.
2. Prefer skills as the primary workflow surface.
3. Use commands only when they are a maintained compatibility shim or a user explicitly wants slash-command behavior.
4. Mention agents when delegation is useful.

Useful searches:

rg -n "<query>" skills commands agents docs
find skills -maxdepth 2 -name SKILL.md | sort

Install Guidance

Use managed install paths:

node scripts/install-plan.js --list-profiles
node scripts/install-plan.js --profile minimal --target codex --json
node scripts/install-apply.js --profile minimal --target codex --dry-run

For specific skill installs:

node scripts/install-plan.js --skills <skill-id> --target codex --json
node scripts/install-apply.js --skills <skill-id> --target codex --dry-run

Warn users not to stack plugin installs and full manual/profile installs unless they intentionally want duplicate surfaces.

Project Onboarding

Use /project-init when the user wants ecc configured for a target repo. The expected sequence is:

1. detect the stack from project files
2. resolve a dry-run install plan
3. inspect existing CODEX.md and settings files
4. ask before applying changes
5. keep generated guidance minimal and repo-specific

Troubleshooting

Ask for the target harness and install path first, then inspect:

• plugin install metadata
• .codex/, .cursor/, .codex/, .gemini/, .opencode/, .codebuddy/, .joycode/, or .qwen/
• hooks/hooks.json
• install-state files
• relevant command/skill files

For repo health, suggest:

npm run harness:audit -- --format text
npm run observability:ready
npm test

Output Templates

Short Recommendation

Use <skill-or-command>. It fits because <reason>.

Canonical file: <path>
Verify with: <command>
Next: <one concrete action>

Search Results

Best matches:
- <path>: <why it matters>
- <path>: <why it matters>

Recommendation: <which one to use first and why>

Install Plan Summary

Detected: <stack evidence>
Target: <harness>
Plan: <profile/modules/skills>
Dry run: <command>
Would change: <paths>
Needs approval before apply: <yes/no>

Related Surfaces

• /project-init: stack-aware onboarding plan for a target repo
• /harness-audit: deterministic readiness scorecard
• /skill-health: skill quality review
• /skill-create: generate a new skill from local git history
• /security-scan: inspect Codex/OpenCode configuration security