How to Create Custom Commands for ECC: A Complete Guide

Creating custom commands for ECC requires adding a markdown file to the commands/ directory with YAML front-matter containing name and description fields, followed by markdown documentation that renders when users invoke /<command-name>.

The affaan-m/ECC repository provides a flexible framework where commands are treated as documentation-first artifacts. When you create custom commands for ECC, you extend the system's capabilities by leveraging the command-registry's automatic discovery mechanism, which scans the commands/ directory at startup and generates the mapping found in docs/COMMAND-AGENT-MAP.md.

Understanding the ECC Command Architecture

How Commands Work in ECC

In the affaan-m/ECC codebase, the command engine interprets every command as a markdown file located in the repository's commands/ directory. When a user types /command-name in a Claude Code session, the system loads the corresponding markdown file, parses its front-matter metadata, and presents the rendered help text. This architecture eliminates complex build steps—placement in the correct directory with proper metadata is sufficient for automatic registration.

Key Files and Locations

Understanding the file structure helps when you create custom commands for ECC:

• commands/<my-command>.md — The markdown definition containing your command's logic and documentation.
• docs/COMMAND-AGENT-MAP.md — Auto-generated mapping file that links command names to their corresponding markdown file paths; updated automatically when new files appear in the commands/ directory.
• commands/skill-create.md — Real-world example demonstrating a command that analyzes git history and generates SKILL files.
• AGENTS.md — Documentation for the 61 built-in agents (such as /plan, /evolve) that can be invoked from within your custom commands.
• README.md — High-level overview of the ECC repository and command system capabilities.

Step-by-Step Guide to Creating Custom Commands

Step 1: Create the Markdown File in commands/

To begin, add a new file to the commands/ directory using kebab-case naming. For example, create commands/my-command.md. The filename should correspond to the trigger name you intend to use, as this file will be automatically scanned by the command-registry loader at startup to build the internal command map.

Step 2: Define Front-Matter Metadata

Every command file must start with YAML front-matter specifying two required fields: name (the trigger without the leading slash) and description (a brief summary shown in /help output). The command-registry reads this metadata to populate docs/COMMAND-AGENT-MAP.md and present the command in help listings.

---
name: my-command
description: Brief one-sentence summary shown in /help
---

Step 3: Write the Command Body

After the front-matter block, use standard markdown to document usage, parameters, workflow, and code snippets. The body renders verbatim when users invoke the command, supporting Bash snippets, inline examples, and links to other documentation. Structure your content with clear headings for Purpose, Usage, Options, and Examples to maximize readability.

Practical Examples

Basic Hello World Command

Here is a minimal implementation showing how to create custom commands for ECC with simple functionality:

---
name: hello-world
description: Prints a friendly greeting.
---

# Hello World

## Usage

```bash
/hello-world [--name <your-name>]

Description

If --name is supplied, the command returns "Hello, !". Otherwise it returns "Hello, world!".

Example

/hello-world --name Alice

### Pipeline Command Composing Multiple Agents

You can reference existing agents and commands to build complex workflows. This example demonstrates invoking built-in agents documented in [`AGENTS.md`](https://github.com/affaan-m/ECC/blob/main/AGENTS.md):

```markdown
---
name: my-pipeline
description: Runs a sequence of existing commands.
---

# My Pipeline

## Workflow

1. `/plan` – generate a project plan.
2. `/code-review` – review the generated code.
3. `/pr` – open a pull request.

## Usage

```bash
/my-pipeline --project my-app

### Advanced Command with Parameters

For commands requiring options and flags, document them in a table format within the markdown body:

```markdown
---
name: deploy-check
description: Validates deployment readiness.
---

# Deploy Check

## Options

| Flag | Description |
|------|-------------|
| `--dry-run` | Show what would happen without side-effects |
| `-v` | Enable verbose output |

## Example

```bash
/deploy-check --dry-run -v

## Referencing Built-in Agents and Commands

When you create custom commands for ECC, you can leverage the 61 built-in agents documented in [`AGENTS.md`](https://github.com/affaan-m/ECC/blob/main/AGENTS.md). Reference these using their slash commands (e.g., `/plan`, `/evolve`, `/help`) within your command's documentation or implementation logic. The [`commands/skill-create.md`](https://github.com/affaan-m/ECC/blob/main/commands/skill-create.md) file provides a concrete example of analyzing repository data and generating SKILL files by orchestrating multiple system capabilities.

## Summary

- **File placement**: Store command definitions as markdown files in the `commands/` directory.
- **Required metadata**: Include `name` and `description` in the YAML front-matter block.
- **Auto-registration**: The command-registry automatically scans `commands/` at startup and updates [`docs/COMMAND-AGENT-MAP.md`](https://github.com/affaan-m/ECC/blob/main/docs/COMMAND-AGENT-MAP.md) without manual intervention.
- **Content flexibility**: Use standard markdown for documentation, supporting tables, code blocks, and references to other commands like `/plan` or `/code-review`.
- **Real-world reference**: Study [`commands/skill-create.md`](https://github.com/affaan-m/ECC/blob/main/commands/skill-create.md) for complex implementations involving git analysis and SKILL file generation.

## Frequently Asked Questions

### Where do I place custom command files in ECC?

Place all custom command files in the `commands/` directory at the repository root. The command-registry loader scans this directory automatically at startup to build the internal mapping. Each file should follow the naming convention `commands/<command-name>.md` to ensure proper discovery and linkage in [`docs/COMMAND-AGENT-MAP.md`](https://github.com/affaan-m/ECC/blob/main/docs/COMMAND-AGENT-MAP.md).

### Do I need to register or compile custom commands after creating them?

No registration step is required. When you save a markdown file to `commands/`, ECC automatically picks it up during the next session initialization. The system regenerates [`docs/COMMAND-AGENT-MAP.md`](https://github.com/affaan-m/ECC/blob/main/docs/COMMAND-AGENT-MAP.md) to reflect the new `name → file-path` mapping without manual intervention.

### Can I call other commands from within my custom ECC command?

Yes. You can reference other commands and agents using their slash notation (e.g., `/plan`, `/code-review`, `/pr`) within your markdown documentation. While the examples show sequential workflows, you can document any orchestration pattern that leverages the 61 built-in agents listed in [`AGENTS.md`](https://github.com/affaan-m/ECC/blob/main/AGENTS.md).

### What metadata is required in the front-matter block?

You must include two YAML fields: `name` (the trigger word without the leading slash) and `description` (a concise summary displayed in `/help` output). This metadata enables the command-registry to identify and catalog your command in [`docs/COMMAND-AGENT-MAP.md`](https://github.com/affaan-m/ECC/blob/main/docs/COMMAND-AGENT-MAP.md), making it discoverable to users.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}