- name
SKILL.md
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add Cecilapp/Cecil --skill cecil -a cursor -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add Cecilapp/Cecil --skill cecil -a claude-code -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add Cecilapp/Cecil --skill cecil -a codex -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add Cecilapp/Cecil --skill cecil -a grok -ySend the copied message in a Grok Bot chat. The Bot fetches this SKILL.md from GitHub and adds it to the skills all your Bots share.
Install this skill: https://github.com/Cecilapp/Cecil/tree/HEAD/skills/cecilFrom the publisher
You are an expert Cecil developer capable of creating and generating static websites with Cecil, a PHP-based static site generator powered by Symfony components and Twig.
Use this skill when:
This file covers what most tasks need. Read the matching reference before working on a topic it covers:
my-site/
├── cecil.yml # Main configuration file (or config.yml)
├── pages/ # Markdown pages
├── layouts/ # Twig templates
├── assets/ # Processed files (CSS, JS, images)
├── static/ # Static files copied as-is
├── data/ # Data collections (YAML/JSON/...)
├── translations/ # UI strings translations (messages.<locale>.yaml)
├── extensions/ # Custom PHP classes (generators, Twig extensions, post-processors, event subscribers)
├── .cache/ # Build cache (generated, `cache.dir`)
└── _site/ # Generated site (`output.dir` or `--output`)
Add .cache/ and _site/ to the site .gitignore.
asset() in a template (or as an image in Markdown): a file linked directly (url() or a raw path) must be in static/static.mounts copies specific files or directories of static/ to a chosen output path)site.data (data/authors.yml → site.data.authors)messages.<locale>.<ext>, used by the trans tag/filter)extensions/MyProject/Generator/CustomGenerator.php)Cecil follows a build pipeline:
Builder → Steps → Generators → Renderer → Output
Steps (Step/): Sequential build phases, in this order
Generators (Generator/): Page generators executed via priority queue
DefaultPages at priority 10 runs before Alias at priority 80).Renderer (Renderer/): Twig-based rendering with custom extensions
Output: Built static site in _site/ directory
.md, also .markdown, .mdown, .mkdn, .mkd, .text, .txt: pages.ext) composed of front matter and body (see references/content.md for the Markdown syntax)---, +++, or ``)pages/ (e.g. pages/blog/post-1.md -> section blog); its index.md (or README.md, handled as index.md) holds the section front matterpages/index.md; it accepts sortby and pagination like a section, and pagesfrom: blog to list the pages of the blog section instead of all pagespages/ define generated paths, slugified (pages/My Projects/Project A.md → /my-projects/project-a/, rendered as my-projects/project-a/index.html); permalinks per section are set with pages.paths (see references/content.md)blog/post-1), used by url(), site.page(), [link](page:blog/post-1) and menusA nested folder that explicitly contains an index.md file becomes a sub-section of its parent Section. A nested folder without an index.md file is not a sub-section: its pages simply belong to the parent section.
pages/
└─ blog # Section "blog"
├─ index.md
├─ post-1.md # Page in "blog"
└─ 2024 # Sub-section (contains an "index.md")
├─ index.md
└─ post-2.md # Page in "blog" AND "blog/2024"
A sub-section:
type, variables, and layout resolution) available at its own URL (e.g. /blog/2024/)blog/list.html.twig for blog/2024 if blog/2024/list.html.twig doesn't exist)blog/2024/06/)Sub-sections support the same front matter variables as any section (sortby, pagination, cascade, circular). Use cascade on a parent index.md to propagate variables down to sub-sections and their pages.
In templates, use page.parent, page.ancestors, page.sections and page.toplevel to build navigation, or include the ready-to-use partials/breadcrumb.html.twig partial.
Previous/next navigation (page.prev / page.next) follows the sections tree: the pages of a top level section and of all its sub-sections are chained depth-first, sorted with the section's sortby, each sub-section index page being followed by its own pages.
Front matter is YAML by default (pages.frontmatter also accepts ini, toml and json). Common variables:
Every predefined variable can be overridden, except section (derived from the folder). Any other variable is a custom one, available in templates as page.<variable>. Front matter is validated (types of predefined variables, plus the rules declared by section or by page in pages.schema, see references/configuration.md): an invalid page is skipped by default (pages.validation).
A file name prefix sets the date (2019-04-23_My post.md) or the weight (1_First project.md) of the page; separators are - and _ by default (pages.prefix.separator).
A section (<section>/index.md) also accepts:
sortby: date (default), updated, title or weight, or a map {variable: date, desc_title: false, reverse: false} (desc_title sorts pages with the same date by descending title); the site default is pages.sortbypagination: {max: 5, path: page} to override pages.pagination, false to disable it, or {enabled: true} to enable it when it is disabled globally (pages.pagination: false)cascade (variables propagated to the section pages, without overriding the variables they already set) and circular (circular prev/next navigation; with sub-sections, only the top-level section value applies)Configuration is defined in cecil.yml or config.yml at project root (read references/configuration.md for the options structure):
title, baseline, baseurl (must end with /), description, author, social, taxonomies, menus, date, themesite variable access (for example site.title)config/default.php; priority is defaults < themes config.yml (the first theme wins) < site config (plus --config files) < env vars (CECIL_*, also read from a .env file) and CLI options (--baseurl, --output, --drafts…)enabled key (e.g. cache: false); in templates, check it with the enabled test ({% if config.cache is enabled %})pages.ext, output.pagetypeformats.<type>, assets.images.responsive.widths…) replaces the default list but is added to the theme list; a map of booleans adjusts the default or theme list instead (e.g. homepage: {rss: true, atom: false})output.formats entries are merged by name: override a default format with only its name and the properties to changeconfig/deprecated.php) make the build fail, with a message giving the source (site, theme or env vars) and the new YAML snippet to usepages.default, indexed by ID (pages.virtual is removed); like any page they are listed (showable, sitemap, homepage) unless they set excluded: true. The built-in default pages (index, 404, robots, sitemap, xsl/*) are declared there too: disable one with pages: {default: {sitemap: {published: false}}} rather than creating a duplicatepage.generated, formerly page.virtual) when it has no content file (section, term, page declared in configuration, etc.) or is a paginated pageDownload Cecil using curl:
curl -LO https://cecil.app/cecil.phar
chmod +x cecil.phar
Requirements: PHP 8.3+ with the fileinfo, gd and mbstring extensions (optional: intl to localize dates in a locale other than en, curl for doctor:links external checks, imagick for better image processing). If the CLI reports a PHP version or extension error, check php -v and php --ini (the CLI may use another php.ini).
If PHP is not available, use the standalone binary for the platform instead (cecil-linux-x64, cecil-linux-arm64, cecil-macos-x64, cecil-macos-arm64, cecil-windows-x64.exe), and replace php cecil.phar with ./cecil in the commands below. The binary has no self-update command, only supports GD for image processing, and its serve command requires a local PHP executable (for the PHP built-in web server).
curl -Lo cecil https://github.com/Cecilapp/Cecil/releases/latest/download/cecil-linux-x64 && chmod +x cecil
xattr -d com.apple.quarantine cecil # macOS only
If Cecil is already installed globally (Homebrew brew install cecilapp/tap/cecil, Scoop, PHIVE or composer global require cecil/cecil), run cecil <command> instead of php cecil.phar <command> (check with cecil --version); it is updated with the same tool, not with self-update.
Use the new:site command to scaffold a new website. It asks questions (title, baseline, base URL, author, language, GitHub Pages workflow, etc.) and creates cecil.yml, pages/index.md, a README.md and a .gitignore: in a non-interactive shell, add -n to use the defaults, then edit cecil.yml:
php cecil.phar new:site -n # `--demo` adds demo content, `--force` overrides an existing site
php cecil.phar new:site my-site -n # in the `my-site` directory
Starter kits are an alternative for a full site (Cecilapp/the-butler blog, Cecilapp/statidocs documentation, etc.): see https://cecil.app/starter-kits/.
Edit cecil.yml:
title: My Site
baseline: A short tagline # shown after the title in the homepage <title>
baseurl: https://example.com/ # must end with /
description: My awesome static site
taxonomies:
categories: category
tags: tag
Create a page with (-n and --name in a non-interactive shell):
php cecil.phar new:page --name=blog/my-post.md -n # `--prefix` adds a date prefix, `--slugify` slugifies the name
new:page uses a page model when it exists: models/<section>.md (e.g. models/blog.md for pages in blog/) or models/default.md, with the %title% and %date% placeholders. Pages can also be created directly as files in pages/.
Then edit the generated file in pages/:
---
title: My First Post
description: Welcome to my blog
date: 2024-05-14
tags: [Welcome, "First post"]
---
# My First Post
This is my first post content.
Cecil ships with built-in templates (resources/layouts/), so a site builds without any template in layouts/. Only create templates to customize the rendering, and prefer extending the built-in ones (see Built-in Templates).
Create Twig templates in layouts/ (for example layouts/page.html.twig):
<!DOCTYPE html>
<html lang="{{ site.language }}">
<head>
<meta charset="utf-8">
{# generates <title>, description, canonical, Open Graph, etc. #}
{{ include('partials/metatags.html.twig') }}
</head>
<body>
<header>
<h1>{{ site.title }}</h1>
</header>
<main>
{{ page.content }}
</main>
<footer>
<p>© {{ site.title }}</p>
</footer>
</body>
</html>
php cecil.phar build
Output is generated in _site/ directory.
php cecil.phar build path/to/site); php cecil.phar help <command> lists its options.--config=config/dev.yml[,other.yml] adds configuration files, merged over cecil.yml from left to right: it does not replace it.build --metrics shows the duration and memory of each step (to profile a slow build); --clear-cache=<regex> only clears the matching cache keys.serve is for local preview only: never use it to host the site, deploy the _site/ output.doctor:links and doctor:seo return a failure exit code according to --fail-on: bad (default), ok (redirections, missing trailing slash), feedback or never. doctor:links also accepts --page, --exclude, --format=json, --include-generated, --timeout, --concurrency, --no-cache and --feedback; its defaults can be set under the doctor.links configuration key. External links checks need the curl PHP extension, and successful results are cached for 24 hours.doctor:seo runs a dry-run build and checks the generated pages; thresholds and checks are set under doctor.seo (e.g. {title: {min: 30, max: 60}, description: {min: 120, max: 160}, content: {min_words: 300}}, and checks booleans: title, description, canonical, h1, og_tags, img_alt, content_length, lang_attribute).Twig templates live in layouts/ and are named layouts/(<section>/)<type>|<layout>.<format>(.<language>).twig (e.g. layouts/page.html.twig, layouts/blog/list.html.twig). For each page, Cecil picks the first existing template in a lookup order, searching the site layouts/, then the theme, then the built-in templates. Read references/templates.md for the full lookup rules and helpers.
Cecil embeds default templates in resources/layouts/ (_default/ layouts, partials/, feeds, sitemap, robots.txt, 404, redirects, JSON outputs, etc.). They are always available to Twig, so they can be rendered, included or extended without being copied into layouts/.
Rules to follow:
Don't recreate what already exists: before writing a template, check whether a built-in one covers the need (feeds, sitemap, robots.txt, 404, redirects, JSON outputs are already provided).
Extend rather than copy: _default/page.html.twig exposes the blocks head, head_metatags, head_css, header, content and footer.
{# layouts/page.html.twig #}
{% extends '_default/page.html.twig' %}
{% block content %}
<article>{{ page.content }}</article>
{% endblock %}
Don't shadow a built-in template by accident: a site file with the same path (e.g. layouts/_default/page.html.twig or layouts/partials/metatags.html.twig) fully replaces the built-in one for the whole site, and can't extends itself.
Extract only as a last resort: php cecil.phar util:templates:extract copies all built-in templates into layouts/; the copies then no longer receive Cecil updates.
Always use partials/metatags.html.twig in the <head> of HTML layouts (already included by _default/page.html.twig): it generates <title>, description, canonical, Open Graph, Twitter/X Card, favicons, feeds and hreflang links, etc. Never add a separate <title>, <meta name="description">, canonical or og:* tags next to it: they would be duplicated.
Make UI strings translatable on multilingual sites: wrap them with {% trans %}…{% endtrans %} or |trans and provide translations/messages.<locale>.yaml files (see references/multilingual.md).
Build URLs with url() (pages, page IDs, menu entries, assets), never by concatenating site.baseurl: <a href="{{ url(page) }}">, {{ url('blog/post-1') }}.
Escape text in attributes yourself: Twig autoescape is disabled by default (layouts.autoescape: false), so {{ page.content }} needs no , but a value printed in an attribute must be escaped ().
When a user reports unexpected behavior or asks about a specific feature, ask them to run php cecil.phar doctor and include the output. If you are uncertain whether a feature is available in the user's Cecil version, say so explicitly and direct them to the official documentation at https://cecil.app/documentation/ rather than guessing version ranges.
cecil.yml syntax and configurationDeprecated configuration option(s): move or remove the listed options as shown in the error messagepages/ directorylayout front matter variable, template naming and lookup rulesphp cecil.phar build -vv for verbose outputUnable to add Twig extension, Unable to load output post processor), the build doesn't fail: check the -v outputphp cecil.phar cache:clear; a new translation file is not detected (cache:clear:translations), and remote assets are cached for 7 days (cache.assets.remote.ttl); while developing templates, cache: {templates: false} disables the templates cachephp cecil.phar doctor:links (internal links) or php cecil.phar doctor:links --internal --externalGet detailed build information:
php cecil.phar build -v # Verbose
php cecil.phar build -vv # Very verbose
php cecil.phar build -vvv # Debug
debug: true in the configuration (or CECIL_DEBUG=true) enables the Twig dump() / d() functions and the Sass source maps.
Build and configure Cecil static sites, with focused guidance for content, templates, and site generation.
---name: cecildescription: Build and configure Cecil static sites, with focused guidance for content, templates, and site generation.---# skills/cecil/SKILL.mdFAQ
Download skills/cecil/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
The publisher keeps it at https://github.com/Cecilapp/Cecil.
Claude, Cursor, Codex, and Grok Build can read a SKILL.md you add from the publisher's repository. Grok Bot installs it when you send the skill's GitHub folder link in a chat.
page/index.htmlexcluded | true to hide the page from lists, sitemap and feeds (formerly exclude) |
language, langref | Language code (default: file suffix) and translations reference |
| Stop the local server |
php cecil.phar edit | Open pages directory with the configured editor (--editor or editor config key) |
php cecil.phar show:config | Display effective configuration (--key=pages.dir to show a single key) |
php cecil.phar show:content | Display content tree (pages, data, static files) |
php cecil.phar doctor | Diagnose site and environment (see also doctor:frontmatter, doctor:seo, doctor:links, doctor:cache) |
php cecil.phar cache:clear | Clear all cache files (or only cache:clear:assets, cache:clear:templates (--fragments), cache:clear:translations) |
php cecil.phar clear | Remove generated files (or only clear:output, clear:temporary / clear:tmp) |
php cecil.phar util:templates:extract | Extract built-in templates into layouts/ (Phar and standalone binary only) |
php cecil.phar util:translations:extract | Extract translation strings from templates |
php cecil.phar about | Display Cecil version and environment information |
php cecil.phar self-update | Update Cecil to the latest version (Phar only; --stable, --preview, --rollback) |
|rawtitle="{{ page.title|e('html_attr') }}"