---
title: "Skills: the guide"
description: "The Éclair skills guide: requirements, installation, starter prompt, quality gates, what to do and avoid, and how to create your own skill."
url: "https://eclaircms.org/en/documentation/skills"
lang: "en"
author: "Thierry Gustin"
published: "2026-11-08"
updated: "2026-11-10"
---

# Skills: the guide

> **Key takeaways** — This guide explains step by step how to use Éclair skills: install the library in your project, start an agent with the right prompt, follow the seven quality gates before any activation, avoid common mistakes and create your own skills. It is for anyone who wants to add a feature to an Éclair 2.0 site with Claude Code, Codex or ChatGPT.

The 57 Éclair skills, in 8 families, help your AI assistant add a feature to your [Éclair 2.0](https://eclaircms.org/en/download) site without breaking what works. Install them in your project, start the agent with the supplied prompt, and activate nothing before the 7 quality gates.

This guide details each step and explains how to write your own skills. Before you start, make a backup as explained in the [Updates, backups and moving](https://eclaircms.org/en/documentation/updates) guide.

## What do you need before you start?

- **An Éclair 2.0 site** and, ideally, a working copy of the code (the official repository cloned), so the agent can run the tests.
- **Python 3** to install and validate the skills, **PHP 8.1 or later** for Éclair’s tools.
- **An assistant that reads skills**: Claude Code or Codex, for example.
- **A recent backup**: Security › Download a backup.

## How do you install the skills in your project?

1. Download the library from [GitHub](https://github.com/Jacckisback/eclair-skills) (Code › Download ZIP, or `git clone`).
2. In its folder, check it is intact with `python3 scripts/validate_skills.py`: the message should report 57 valid skills.
3. List families and skills with `python3 scripts/install_skills.py --list`.
4. Install what you need, by family (`--category design`) or by name (`--skill eclair-seo-audit`), with `--project /path/to/my-site`.
5. For Claude Code, copy the installed folders from `.agents/skills/` to `.claude/skills/`.

```bash
python3 scripts/validate_skills.py
python3 scripts/install_skills.py --list
python3 scripts/install_skills.py --project /path/to/my-site --category foundation
python3 scripts/install_skills.py --project /path/to/my-site --skill eclair-wordpress-migration
python3 scripts/install_skills.py --project /path/to/my-site --all
```

> **Tip** — Start with the `foundation` family: its eight skills set the shared rules (architecture, storage, rights, routes, cache, security, tests) that all the others depend on.

## How do you start the agent with the right prompt?

Open your assistant in the project folder and give it a clear starter prompt. This one ships with the library:

```text
Analyse this Éclair CMS project starting with eclair/index.php and docs/SKILLS-GUIDE.md. Use the skills eclair-architecture, eclair-extension-builder, eclair-security-audit and eclair-test-suite. Describe the requested feature in terms of the native eclair-extension/1 capabilities. Create the extension files under site/extensions/<id>/ without modifying the core. Before proposing activation, run php tools/validate.php <extension> --json, php tests/run.php and php tools/measure.php --check. If a capability is missing, stop that part and create an RFC and tests; do not invent an API.
```

Then add your request in one or two sentences, with the constraints that matter to you: audience, languages, volume, personal data.

## What checks before activating a feature?

The library defines seven quality gates. A feature is only activated once all of them are passed.

| Gate | What is checked |
| --- | --- |
| 0 | Éclair version, commit and the site’s real capabilities (capabilities API) |
| 1 | Package stored in site/extensions/&lt;id>/, eclair-extension/1 manifest, file fingerprints, core untouched |
| 2 | Official validator: php tools/validate.php &lt;folder> --json returns valid: true |
| 3 | Full test suite: php tests/run.php |
| 4 | Performance budgets: php tools/measure.php --check |
| 5 | Negative security tests, per-object rights, isolated private cache, backup and restore |
| 6 | Human review, activation from the admin and rollback tested |

## What to do

- Describe the business need, not the technique: the agent picks the skills.
- Let the agent read the site’s capabilities before writing code.
- Test on a copy of the site, never directly in production.
- Keep a record of decisions: the agent writes a short architecture note.
- Plan the rollback: deactivating a feature keeps its data.

## What not to do

- Modify `app/`, `assets/`, `index.php` or the updater: an update would overwrite everything.
- Activate a feature that hasn’t passed the validator and the tests.
- Put a cart, a member area or a forum into production while the core doesn’t provide the contract.
- Believe an SEO, GEO or Lighthouse score is guaranteed: they are measurements to repeat.
- Give the agent secrets in plain text: they belong in `data/ext/<id>/secrets.php`.

## How do you create your own skill?

```text
skills/eclair-my-trade/
├── SKILL.md
└── references/
    ├── acceptance.md
    └── native-contract.md
```

1. Create a `skills/eclair-<name>/` folder with a `SKILL.md` file.
2. At the top of the file, set `name` and a `description` that says when to use it: this is what the agent reads to decide.
3. Write the mandatory diagnosis, the procedure, the deliverables, the security invariants and the acceptance criteria.
4. Add your useful documents in `references/`: a skill must be self-contained.
5. Declare it in `catalog.json`, then run `python3 scripts/validate_skills.py` and `python3 scripts/check_release.py --write`.
6. Test it on a real project, then propose it to the library with a pull request.

## What if something gets stuck?

**The validator rejects the package**: Read the JSON message: it names the file or manifest field at fault. Fix it, then run the validation again.

**The agent wants to modify the core**: Refuse and restate the rule: everything must live in site/. If a capability is missing, ask for an RFC and a blocking test.

**A capability is missing (customer accounts, payment…)**: That’s expected for some families: keep the design and the tests, and wait for the core to open the contract.

## Questions about using skills

### Where are the skills installed?

In your project’s `.agents/skills/` folder. For Claude Code, copy them into `.claude/skills/`.

### Can I install a single skill?

Yes, with `--skill eclair-<name>`. You can repeat the option to install several.

### How do I update a skill?

Download the new version of the library, review the changes, then reinstall with `--force`.

### Do skills work without a connection to my live site?

Yes. They work on your copy of the project; that is even recommended.

[See the library on GitHub](https://github.com/Jacckisback/eclair-skills)

[The 57 skills, family by family](https://eclaircms.org/en/skills)