How to Create Custom Skills for ECC: A Complete Developer Guide

Create custom skills for ECC by authoring a SKILL.md file with YAML frontmatter, placing it in a kebab-case folder under skills/, and registering it via the plugin marketplace or manual installation to ~/.claude/skills/.

ECC (Everything Claude Code) treats skills as the primary workflow surface within its agentic ecosystem. According to the affaan-m/ECC repository source code, a custom skill is a self-contained markdown file that Claude Code auto-activates based on metadata and trigger keywords. This guide explains the exact architecture, required frontmatter schema, and registration process to extend ECC with your own domain-specific expertise.

Skill Anatomy and Frontmatter Schema

Every skill file must follow a strict frontmatter schema at the top of the markdown. The canonical example lives in skills/backend-patterns/SKILL.md.

---
name: <kebab-case-skill-id>
description: Short, user-facing description (appears in skill list)
origin: ECC
---

Key fields to include:

• name – Must be lowercase, hyphenated, and match the directory name exactly. This identifier powers invocation commands like /skill-name.
• description – A one-sentence summary that appears in the skill picker UI.
• origin – Set to ECC for built-in skills; third-party contributors may define custom origins.

The body of the markdown file contains the knowledge payload: conceptual explanations, design patterns, command snippets, and optional JSON/YAML sections for tooling. ECC parses this content at load time, extracting the frontmatter to register the skill in the engine.

File Placement and Directory Structure

Create a new folder under skills/ that matches the skill name, then place the SKILL.md file inside it:

ECC/
├─ skills/
│   ├─ my-custom-skill/
│   │   └─ SKILL.md

This path is critical because the installer copies only the skills/ tree into the user’s ~/.claude/skills/ directory (or equivalent locations for other harnesses). As noted in the repository README’s “What’s Inside” section, the installer maintains this hierarchy to ensure agents can discover dependencies consistently.

Structuring Skill Content

A well-structured skill typically contains four core sections to maximize utility:

When to Activate – Clarifies contexts where the skill should auto-suggest. Example: “When the user wants to add a new API endpoint or update REST conventions.”

Core Principles – High-level guidance and design philosophies. Example: “Prefer resource-based URLs, use proper HTTP status codes.”

Usage Patterns / Code Examples – Concrete snippets showing patterns in action. Reference the API Design Patterns section in skills/backend-patterns/SKILL.md for implementation details.

Reference Links – Absolute GitHub URLs pointing to related ECC assets (agents, rules, or other skills). Example: [coding-standards skill](https://github.com/affaan-m/ECC/blob/main/skills/coding-standards/SKILL.md).

Registering the Skill

After adding the skill to the repository, you must register it so Claude Code recognizes the new capability.

Via Plugin Marketplace (Recommended):

/plugin marketplace add https://github.com/affaan-m/ECC
/plugin install ecc@ecc

The installer automatically copies the new skill into ~/.claude/skills/ and updates the AGENTS.md manifest so dependent agents can discover it.

Manual Installation:

mkdir -p ~/.claude/skills/ecc
cp -R skills/my-custom-skill ~/.claude/skills/ecc/

Manual installation bypasses the marketplace but requires you to verify the AGENTS.md manifest manually to ensure agent compatibility.

Auto-Activation and Trigger Keywords

ECC indexes trigger keywords to suggest skills without explicit user commands. Add a Trigger Keywords section in the markdown body:

## Trigger Keywords

- `api design`
- `rest endpoint`
- `resource url`

The harness scans these headings and indexes the words; when user queries contain matches, the skill surfaces as a suggestion. This mechanism is documented in the README’s “Token Optimization” section to maximize context efficiency.

Testing Your Skill

Before merging, run the ECC verification loop to validate integrity:

/quality-gate

This command checks for proper frontmatter syntax, duplicate skill names, and markdown linting. A passing report guarantees the skill loads correctly in downstream projects and integrates with the agentic ecosystem.

Publishing to the Repository

Once verification passes, open a Pull Request against the main branch. Follow the conventional commit format described in CONTRIBUTING.md. The CI pipeline automatically runs the full test suite (over 9,000 tests) to validate the skill before merging.

Complete Skill Template

Below is a runnable template you can adapt for your custom skill:

---  
name: my-custom-skill  
description: Demonstrates how to add a new REST endpoint with validation.  
origin: ECC  
---  

## When to Activate  

- Adding a new HTTP route in a Next.js API.  
- Updating an existing CRUD controller.  

## Core Principles  

- Keep URLs noun-based and plural.  
- Return appropriate HTTP status codes.  

## API Design Pattern  

```typescript
// PASS: Resource-based URL
GET    /api/v1/widgets               # List widgets

GET    /api/v1/widgets/:id           # Retrieve one

POST   /api/v1/widgets               # Create

PUT    /api/v1/widgets/:id           # Replace

PATCH  /api/v1/widgets/:id           # Partial update

DELETE /api/v1/widgets/:id           # Delete

Validation Example (Zod)

import { z } from "zod";

const CreateWidgetSchema = z.object({
  name: z.string().min(1).max(100),
  price: z.number().positive(),
});

export async function POST(req: Request) {
  const payload = await req.json();
  const parsed = CreateWidgetSchema.safeParse(payload);
  if (!parsed.success) {
    return NextResponse.json(
      { error: "Validation failed", details: parsed.error.errors },
      { status: 422 }
    );
  }
  // ... proceed with creation ...
}

Trigger Keywords

• rest api
• http endpoint
• zod validation

## Summary

- **Custom skills** are self-contained markdown files ([`SKILL.md`](https://github.com/affaan-m/ECC/blob/main/SKILL.md)) stored in `skills/<kebab-case-name>/` directories.
- **Frontmatter** requires three fields: `name` (kebab-case), `description` (one sentence), and `origin` (ECC).
- **Registration** occurs via `/plugin install ecc@ecc` or manual copy to `~/.claude/skills/ecc/`.
- **Trigger keywords** in a dedicated markdown section enable auto-activation based on user queries.
- **Testing** requires running `/quality-gate` to validate frontmatter and markdown before submitting a PR.
- **Key reference files**: [`AGENTS.md`](https://github.com/affaan-m/ECC/blob/main/AGENTS.md) (agent discovery), [`CONTRIBUTING.md`](https://github.com/affaan-m/ECC/blob/main/CONTRIBUTING.md) (PR guidelines), and [`skills/backend-patterns/SKILL.md`](https://github.com/affaan-m/ECC/blob/main/skills/backend-patterns/SKILL.md) (canonical example).

## Frequently Asked Questions

### What is the exact file naming convention for ECC skills?

The skill file must be named exactly [`SKILL.md`](https://github.com/affaan-m/ECC/blob/main/SKILL.md) (uppercase) and placed inside a kebab-case folder under `skills/`. The folder name must match the `name` field in the frontmatter. For example, a skill named `api-design` lives at [`skills/api-design/SKILL.md`](https://github.com/affaan-m/ECC/blob/main/skills/api-design/SKILL.md).

### How does ECC know when to suggest my custom skill automatically?

ECC parses the **Trigger Keywords** section in your markdown body and indexes those terms. When a user’s query contains words like `rest api` or `zod validation`, the engine suggests the skill. Explicit invocation via `/skill-name` also works regardless of triggers.

### Can I reference other ECC assets from within my skill?

Yes. Include absolute GitHub URLs in your markdown linking to related files like [`skills/coding-standards/SKILL.md`](https://github.com/affaan-m/ECC/blob/main/skills/coding-standards/SKILL.md) or [`rules/common/coding-style.md`](https://github.com/affaan-m/ECC/blob/main/rules/common/coding-style.md). The [`AGENTS.md`](https://github.com/affaan-m/ECC/blob/main/AGENTS.md) manifest maintains the master list of agents for cross-referencing dependencies.

### What happens if my skill fails the `/quality-gate` verification?

The verification loop checks for malformed frontmatter, duplicate skill identifiers, and markdown linting errors. Failures block PR merging because they prevent the skill from loading in user environments. Fix the reported syntax issues and re-run `/quality-gate` until it passes.

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