Creating Custom ECC Skills

Skills are the most extensible surface in ECC. Any pattern you find yourself repeating — a deployment checklist, a domain-specific review workflow, a team coding convention — can be encoded as a skill and shared across every session, every project, and every team member. This page covers how skills are structured, the placement policy that governs where they live, how to create and test them, and how to contribute them back to the library.

What Is a Skill?

A skill is a knowledge module that the harness loads based on context. It provides domain expertise, workflow definitions, reference material, and code patterns that the model applies when the task matches. Unlike rules (always active) or agents (explicitly delegated), skills are passive knowledge loaded on demand. The key distinction:

Component	Purpose	When it activates
Skill	Knowledge repository	Context-based (automatic or named)
Agent	Task executor	Explicit delegation
Command	User-triggered action	User runs `/command`
Hook	Event automation	Tool-use lifecycle events
Rule	Persistent constraint	Always active

If you’re encoding a reusable workflow, a pattern library, a checklist, or domain expertise — it belongs in a skill.

Skill Architecture

Single-file skill

The simplest form: a single .md file dropped into the skills directory.

~/.claude/skills/
  my-deployment-checklist.md
  team-api-conventions.md

Use the single-file form for lightweight checklists, quick reference patterns, or narrow topic skills.

Multi-file skill

A directory with a SKILL.md at its root plus optional supporting files:

~/.claude/skills/
  my-skill-name/
    SKILL.md               # Required: main skill definition
    examples/              # Optional: code examples
    │   ├── basic.ts
    │   └── advanced.ts
    references/            # Optional: links, supplementary docs
        └── links.md

Use the multi-file form when the skill benefits from separated examples, codemaps, or supplementary reference material.

SKILL.md structure

Every SKILL.md begins with YAML frontmatter:

---
name: your-skill-name
description: One-line description used for auto-activation and skill list display.
origin: ECC
---

Field	Required	Description
`name`	Yes	Lowercase, hyphenated identifier — e.g. `react-hook-patterns`
`description`	Yes	One sentence. Used for auto-activation matching and `npx ecc catalog` display
`origin`	No	Source identifier: `ECC`, `community`, or your project name
`tags`	No	Array of tags for categorisation
`version`	No	Version string for tracking updates
`argument-hint`	No	Hint shown when invoking the skill with an argument, e.g. `<path/to/*.plan.md>`

Creating Your First Skill

Choose a focused scope

Good skills are specific and actionable. One skill equals one domain or workflow.

Good scope	Too broad
`react-hook-patterns`	`react`
`postgresql-indexing`	`databases`
`pytest-fixtures`	`python-testing`
`nextjs-app-router`	`nextjs`

If you find yourself writing “and also…” in the skill title, split it into two skills.

Create the skill directory

For a multi-file skill:

mkdir -p ~/.claude/skills/your-skill-name

For a single-file skill:

touch ~/.claude/skills/your-skill-name.md

Write SKILL.md

Use this minimal template as your starting point:

---
name: your-skill-name
description: Brief description of when to use this skill.
origin: ECC
---

# Your Skill Title

Brief overview in 1–2 sentences.

## When to Activate

- Scenario 1
- Scenario 2
- Scenario 3

## Core Concepts

### Concept 1

Explanation with examples.

## Code Examples

\`\`\`typescript
// Practical, tested example
\`\`\`

## Anti-Patterns

### ❌ Don't do this

\`\`\`typescript
// Bad example
\`\`\`

### ✅ Do this instead

\`\`\`typescript
// Good example
\`\`\`

## Best Practices

- Actionable guideline 1
- Actionable guideline 2

## Related Skills

- `related-skill-1`
- `related-skill-2`

Add actionable content

The most important principle: show, don’t tell.Every claim should be backed by a copy-pasteable example. Every pattern should have a corresponding anti-pattern. Every workflow should include a verification checklist.Guidelines:

Length: 200–500 lines typical; 800 lines maximum
Code blocks: always include a language identifier (```typescript, ```python, etc.)
Headers: use ## and ### hierarchy — no # after the title
Lists: - for unordered, 1. for ordered steps
Tables: for comparisons, reference matrices, and checklists

The When to Activate section is critical for auto-activation. Be specific — list the concrete scenarios in which the model should pull this skill.

Test locally

Copy the skill to your skills directory and test it in a Claude Code session:

# Copy to Claude Code skills directory (if developing outside of it)
cp -r skills/your-skill-name ~/.claude/skills/

# Verify it appears in the skill list
npx ecc skills-health

In your harness session, ask about the skill’s domain and verify the model is referencing your patterns, examples, and guidelines.Validation checklist before submitting:

YAML frontmatter is valid (no syntax errors)
name follows lowercase-with-hyphens convention
description clearly states when to use the skill
All code examples compile and run
No sensitive data (API keys, tokens, personal paths)
Related Skills references exist
When to Activate section is specific

Skill Placement Policy

ECC has four types of skills with distinct placement rules:

Curated skills — shipped with ECC

Location: skills/<skill-name>/ in the ECC repository
Installed by: npx ecc install manifests
Provenance: origin field in SKILL.md frontmatter (no .provenance.json required)These are the skills you contribute via pull request. They are validated by scripts/ci/validate-skills.js and must have a non-empty SKILL.md.

Learned skills — generated by continuous-learning

Location: ~/.claude/skills/learned/<skill-name>/
Created by: continuous-learning and continuous-learning-v2 at session end
Required: .provenance.json sibling to SKILL.mdNever committed to the repo. Loaded at runtime when the directory exists.

// .provenance.json
{
  "source": "session-2025-07-14",
  "created_at": "2025-07-14T15:30:00Z",
  "confidence": 0.85,
  "author": "continuous-learning-v2"
}

Imported skills — from external sources

Location: ~/.claude/skills/imported/<skill-name>/
Created by: manual copy or future importer tooling
Required: .provenance.json sibling to SKILL.mdSkills from community repos, personal configs, or team-internal libraries that you don’t want to ship in the ECC repo.

Evolved skills — from instinct clustering

Location: ~/.claude/homunculus/evolved/skills/ (global) or ~/.claude/homunculus/projects/<hash>/evolved/skills/ (per-project)
Created by: instinct-cli evolveGenerated by clustering instincts into higher-level skills. Provenance is inherited from source instincts; no separate .provenance.json required.

Only curated skills (in skills/ in the repo) appear in install manifests and are copied during npx ecc install. Learned, imported, and evolved skills live exclusively in the user’s home directory and are never shipped.

Skill Naming Conventions

From the skill placement policy: Keep the original name when:

The contribution is close to a direct port from an upstream source
The name is descriptive and neutral (e.g. nestjs-patterns, fastapi-patterns)
The surface still behaves like the upstream concept

Rename when:

ECC meaningfully expands or repackages the original work
The original name is vendor-forward rather than workflow-forward
The contribution overlaps an existing ECC surface and needs a clearer boundary

Examples:

Keep nestjs-patterns (framework name, neutral, workflow-forward)
Rename a broad planning import to product-capability or lead-intelligence if ECC restructured the scope
Prefer social-graph-ranker over an upstream-branded name for a graph primitive

Skill vs. Other Surfaces

Before creating a skill, verify it’s the right surface:

Use a skill when…	Use something else when…
It’s reusable domain knowledge	It’s a one-time project setup → use a rule
It activates by context	It’s always active → use a rule
It defines a workflow	It’s a single user action → use a command
It provides patterns	It executes a task autonomously → use an agent
It’s on-demand reference	It fires on tool-use events → use a hook

ECC prefers the narrowest surface that accomplishes the goal. Avoid creating a skill that exists mainly to tell users to install an unvetted third-party package.

Skill Adaptation Policy

When adapting an existing skill from another open-source repo or personal config:

Copy the idea, not the branding. Adapt to ECC’s install surfaces and conventions.
Remove external runtime assumptions. ECC is harness-native; don’t encode assumptions about a specific third-party runtime.
Ask the review questions:
- Is this a real reusable surface in ECC, or documentation for another tool?
- Does the name match the ECC-shaped surface?
- Is there already an ECC skill that owns most of this behaviour?
- Would an ECC user understand this skill without knowing the upstream repo?

SKILL.md Template

Here is a complete template covering all major sections:

---
name: your-skill-name
description: One-line description of when to use this skill.
origin: ECC
tags: [workflow, language, security]
version: 1.0.0
---

# Your Skill Title

Brief overview (1–2 sentences) of what this skill covers and when it applies.

## When to Activate

- Specific scenario 1 (e.g., "Writing a new REST API endpoint")
- Specific scenario 2 (e.g., "Refactoring an existing service layer")
- Specific scenario 3 (e.g., "Reviewing code for [domain] compliance")

## Prerequisites

- Requirement 1 (e.g., "Tests passing on the current branch")
- Requirement 2 (e.g., "Feature branch created")

## Core Concepts

### Concept 1

Explanation with a concrete, copy-pasteable example.

\`\`\`typescript
// Example demonstrating the concept
\`\`\`

### Concept 2

Another pattern, again with an example.

## Anti-Patterns

### ❌ Don't do this

\`\`\`typescript
// What not to do, with a comment explaining why
\`\`\`

### ✅ Do this instead

\`\`\`typescript
// The correct approach
\`\`\`

## Workflow Steps

### Step 1: [Name]

Description of what happens in this step.

\`\`\`bash
# Any commands for this step
\`\`\`

### Step 2: [Name]

...

## Verification Checklist

- [ ] Check 1
- [ ] Check 2
- [ ] Check 3

## Troubleshooting

| Problem | Solution |
|---------|----------|
| Symptom 1 | Fix 1 |
| Symptom 2 | Fix 2 |

## Related Skills

- `related-skill-1` — brief note on how it relates
- `related-skill-2` — brief note on how it relates

Contributing a Skill to ECC

Fork and clone

gh repo fork affaan-m/everything-claude-code --clone
cd everything-claude-code

Create a feature branch

git checkout -b feat/skill-your-skill-name

Add your skill

mkdir -p skills/your-skill-name
# Write SKILL.md following the template above

Validate locally

# Check YAML frontmatter
head -10 skills/your-skill-name/SKILL.md

# Verify structure
ls -la skills/your-skill-name/

# Run tests if available
npm test

Commit and push

git add skills/your-skill-name/
git commit -m "feat(skills): add your-skill-name skill"
git push -u origin feat/skill-your-skill-name

Open a pull request

Use this PR template:

## Summary

Brief description of the skill and why it's valuable.

## Skill Type

- [ ] Language standards
- [ ] Framework patterns
- [ ] Workflow
- [ ] Domain knowledge
- [ ] Tool integration

## Testing

How I tested this skill locally.

## Checklist

- [ ] YAML frontmatter valid
- [ ] Code examples tested
- [ ] Follows skill guidelines
- [ ] No sensitive data
- [ ] Clear activation triggers

Skill Evolution via Continuous Learning

ECC’s continuous-learning-v2 skill automatically extracts patterns from your sessions and writes them as learned skills to ~/.claude/skills/learned/. Over time, patterns that prove consistently useful can be promoted:

Review learned skills periodically with /skill-stocktake
Identify patterns that have become stable and generalisable
Promote them to curated skills by moving and cleaning them up for the ECC repo
Submit a PR following the contribution workflow above

This creates a feedback loop: your real usage patterns flow from sessions into learned skills, and the best learned skills eventually graduate into the curated library.

Run /skill-health inside your harness to audit installed skills, check for broken references, and identify gaps in your installation relative to the current project’s tech stack.

CLI Reference

Skills Library

Hooks Reference

Configuration

Creating Custom ECC Skills

What Is a Skill?

Skill Architecture

Single-file skill

Multi-file skill

SKILL.md structure

Creating Your First Skill

Skill Placement Policy

Skill Naming Conventions

Skill vs. Other Surfaces

Skill Adaptation Policy

SKILL.md Template

Contributing a Skill to ECC

Skill Evolution via Continuous Learning

Build docs developers (and LLMs) love

CLI Reference

Skills Library

Hooks Reference

Configuration

Documentation Index

​What Is a Skill?

​Skill Architecture

​Single-file skill

​Multi-file skill

​SKILL.md structure

​Creating Your First Skill

​Skill Placement Policy

​Skill Naming Conventions

​Skill vs. Other Surfaces

​Skill Adaptation Policy

​SKILL.md Template

​Contributing a Skill to ECC

​Skill Evolution via Continuous Learning

Build docs developers (and LLMs) love

What Is a Skill?

Skill Architecture

Single-file skill

Multi-file skill

SKILL.md structure

Creating Your First Skill

Skill Placement Policy

Skill Naming Conventions

Skill vs. Other Surfaces

Skill Adaptation Policy

SKILL.md Template

Contributing a Skill to ECC

Skill Evolution via Continuous Learning