ecc-guide

name	ecc-guide
description	Guide users through ecc's current agents, skills, commands, hooks, rules, install profiles, and project onboarding by reading the live repository surface before answering.
origin	community

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