---
name: ecc-guide
description: Answer questions about ECC by reading the live repo surface — agents, skills, commands, hooks, rules, install profiles, and docs — instead of memory. Use when the user asks what ECC includes, how to install or reset it, which skill or command fits a task, or how project onboarding works.
metadata:
  origin: community
---

# ECC Guide

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

## 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:

```bash
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:

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

### Install Guidance

Use managed install paths:

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

For specific skill installs:

```bash
node scripts/install-plan.js --skills <skill-id> --target claude --json
node scripts/install-apply.js --skills <skill-id> --target claude --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 `CLAUDE.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
- `.claude/`, `.cursor/`, `.codex/`, `.gemini/`, `.opencode/`, `.codebuddy/`, `.joycode/`, or `.qwen/`
- `hooks/hooks.json`
- install-state files
- relevant command/skill files

For repo health, suggest:

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

## Output Templates

### Short Recommendation

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

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

### Search Results

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

Recommendation: <which one to use first and why>
```

### Install Plan Summary

```text
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 Claude/OpenCode configuration security