- name
SKILL.md
技能文件保留在发布者的仓库中。
在终端中粘贴复制的命令。它会把这个 SKILL.md 安装到对应的智能体中。
npx skills add Cecilapp/Cecil --skill cecil-theme -a cursor -y在终端中粘贴复制的命令。它会把这个 SKILL.md 安装到对应的智能体中。
npx skills add Cecilapp/Cecil --skill cecil-theme -a claude-code -y在终端中粘贴复制的命令。它会把这个 SKILL.md 安装到对应的智能体中。
npx skills add Cecilapp/Cecil --skill cecil-theme -a codex -y在终端中粘贴复制的命令。它会把这个 SKILL.md 安装到对应的智能体中。
npx skills add Cecilapp/Cecil --skill cecil-theme -a grok -y在 Grok Bot 聊天中发送复制的消息。Bot 会从 GitHub 获取这个 SKILL.md,并添加到你所有 Bot 共享的技能中。
Install this skill: https://github.com/Cecilapp/Cecil/tree/HEAD/skills/cecil-theme来自发布者
You are an expert Cecil theme developer. You create reusable themes for Cecil: full visual themes (layouts, styles, assets) and small component themes (a feature plugged into any site or theme), packaged for Composer like the official Cecilapp themes.
For general Cecil usage (content, configuration, CLI), see the cecil skill.
Use this skill when:
layouts/ into a reusable themeflexsearch, pwa, darkmodetoggle, ogimage) into a site or a visual theme; ask the user first (see "Ask the user before installing")cecil/theme-<name>)Read the matching reference before working on a topic it covers:
A theme is a website without pages, stored in themes/<name>/ and enabled in the site configuration:
theme: hyde
# or, for several themes (the first one overrides the others)
theme:
- pwa
- hyde
Resolution rules (from src/):
Consequences:
config.yml (not config.yaml); it's the only one loaded.themes/<name>/layouts/ or themes/<name>/config.yml exists; otherwise the build fails with Theme "<name>" not found. Did you forgot to install it?. A theme without layouts/ (config, data or assets only) is supported._default/home, _default/term, _default/vocabulary or _default/404 is picked before a theme's _default/list or _default/page: ship these layouts in the theme to control them. The built-ins extend ['page.html.twig', '_default/page.html.twig'] and fill the content block, so the theme base layout must define a content block.static.exclude, output.pagetypeformats.<type>) replaces Cecil's default list; only a site list is combined with the theme list.theme option of its config.yml (e.g. theme: [fontawesome]): they are enabled with it (layouts, assets, static files, translations, extensions and config.yml) and added after the themes of the site, so the theme overrides the themes it requires. Required themes must be installed too: declare them in the require section of the theme's composer.json. This requires Cecil 9.29 or later: before, the config.yml of a required theme is not loaded (and the requirement is ignored with the string form theme: a), so document the full list to declare (e.g. theme: [links, fontawesome]) if the theme supports older versions.themes/<name>/extensions/ (autoloaded, path matching the namespace or extensions.autoload PSR-4 mappings; use the theme name as namespace, not the reserved Cecil\), registered in its config.yml as Twig extensions (layouts.extensions), generators (pages.generators), post-processors (output.postprocessors) or build events subscribers (); prefer a single plugin (, a class extending ) registering all of them.theme-<name>/
├─ .editorconfig
├─ .gitattributes # * text=auto
├─ .gitignore # vendor/
├─ composer.json
├─ config.yml # default config + namespaced theme options
├─ theme.yml # optional metadata
├─ LICENSE
├─ README.md
├─ docs/
│ └─ screenshot.png
├─ assets/ # processed by asset(): css/, sass/, js/, images
├─ static/ # copied as-is: favicon.ico, fonts/
├─ data/ # optional data files (site.data.*)
├─ extensions/ # optional PHP classes (Twig extensions, generators)
├─ layouts/
│ ├─ _default/
│ │ ├─ page.html.twig # base layout (defines blocks, including `content`)
│ │ ├─ list.html.twig # sections
│ │ ├─ home.html.twig # otherwise the built-in one is used
│ │ ├─ term.html.twig # otherwise the built-in one is used
│ │ ├─ vocabulary.html.twig
│ │ └─ 404.html.twig
│ ├─ <section>/ # optional per-section layouts (e.g. blog/page.html.twig)
│ ├─ components/ # optional Twig components ({% x:<name> %} or <x-name>)
│ ├─ partials/ # header, footer, nav, pagination, post-item...
│ │ └─ notes/ # optional Markdown notes templates (`:::<type>` → <type>.html.twig)
│ └─ macros/ # optional reusable macros
└─ translations/
└─ messages.fr.yml
Put layouts under _default/: this way a site can still provide its own top-level page.html.twig or list.html.twig, which take priority in the lookup.
A component theme only ships what it needs, for example (structure of theme-flexsearch):
theme-<name>/
├─ .github/workflows/demo.yml # builds demo/ and deploys it to GitHub Pages
├─ .gitattributes # export-ignore for .*, /demo, /docs
├─ composer.json
├─ config.yml # new generated pages, output formats, options
├─ theme.yml
├─ README.md
├─ assets/<name>/ # namespaced assets (e.g. flexsearch/flexsearch.css)
├─ demo/ # demo website using the theme
│ ├─ config.yml
│ ├─ layouts/_default/page.html.twig
│ ├─ pages/
│ └─ link.php # links the repository as demo/themes/<name>
├─ docs/screenshot.png
├─ layouts/
│ ├─ _default/<layout>.<format>.twig
│ ├─ partials/<name>.html.twig # snippet to include in <head> or <body>
│ ├─ partials/<name>/*.html.twig # optional sub-partials (e.g. trigger + dialog)
│ └─ macros/<name>.twig # macros to import
└─ translations/messages.fr.yml
Put a component theme's assets in an assets/<name>/ subfolder so they don't collide with the site's or another theme's files.
Before scaffolding, ask the user which features the theme needs and whether official component themes should provide some of them (search, dark mode, PWA, icons…), as described in "Ask the user before installing". In the same message, confirm the use of the built-in metatags partial (see Step 4).
curl -LO https://cecil.app/cecil.phar
php cecil.phar new:site -n --demo
rm -rf layouts # make sure the theme's layouts are used
mkdir -p themes/<name>
Develop the theme directly in themes/<name>/ and enable it in the site cecil.yml (created by new:site; config.yml is only loaded when there is no cecil.yml):
theme:
- <name>
config.ymlProvide sensible Cecil defaults the theme relies on, plus the theme options under a namespace named after the theme:
# Cecil config required by the theme
taxonomies:
tags: tag
pages:
pagination:
max: 10 # only set what differs from Cecil defaults
# Theme options
<name>:
sidebar:
sticky: true
color: '' # red, orange, green, blue...
reverse: false
Rules:
?? or |default(), knowing that |default() also replaces empty values (false, '', 0, []), not only undefined ones:
?? when the user can disable or empty an option, and the fallback is truthy: site.<name>.breadcrumb ?? true, site.<name>.logo ?? 'logo.svg' (logo: '' hides it), site.<name>.toc.min ?? 2 (0 is kept). With |default(true), breadcrumb: false would be ignored.|default() is fine when the fallback is falsy (site.<name>.reverse|default(false), page.blocks|default([])), or when an empty value must be replaced (|default('Latest posts')).?? in parentheses inside a condition combined with other operators: (site.<name>.toc.enabled ?? true) and (page.toc ?? true).taxonomies if the theme displays tags or categories.static.exclude, pages.ext…): a theme list replaces the default list instead of extending it.title, baseurl, description…) out of the theme config.theme.yml (optional metadata)name: <Name>
github: https://github.com/<vendor>/theme-<name>/
author:
- name: <Author>
url: <https://author.tld>
layouts/_default/page.html.twig defines the HTML skeleton and blocks that other layouts (and users) can override:
<!DOCTYPE html>
<html lang="{{ site.language }}">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
{{- include('partials/metatags.html.twig', {page, site}, with_context = false) }}
{%- block head_css %}
{{ html(asset(['css/base.css', 'css/<name>.css']), {title: '<Name>'}, {preload: true}) }}
{%- endblock head_css %}
{{- include('partials/pwa.html.twig', {site}, with_context = false, ignore_missing = true) }}
</head>
<body class="{{ site.<name>.reverse|default(false) ? 'reverse' }}">
{%- block header %}
{{ include('partials/site-header.html.twig') }}
{%- endblock header %}
<main>
{%- block content %}
<article>
<h1>{{ page.title }}</h1>
{%- if page.date %}
<time datetime="{{ page.date|date('c') }}">{{ page.date|format_date('long') }}</time>
{%- endif %}
{{ page.content }}
</article>
{%- endblock content %}
</main>
{%- block footer %}
{{ include('partials/site-footer.html.twig') }}
{%- endblock footer %}
{%- block scripts %}{% endblock scripts %}
</body>
</html>
Guidelines:
partials/metatags.html.twig in the <head> of every HTML base layout, and never hand-write <title>, description, canonical, Open Graph or Twitter tags next to it (they would be duplicated). Since it replaces the theme's own <title>, confirm with the user first, explaining the benefit in one line, e.g.: "I'll use Cecil's built-in metatags partial: it generates the title, description, canonical, favicons, Open Graph/Twitter cards, feeds, hreflang alternates (and optional JSON-LD) from front matter and config, with no code to maintain. OK?" Only skip it if the user explicitly declines; in that case, document in the README which tags the theme outputs.favicon.svg, favicon.png resized, favicon.ico, from assets or static) and outputs JSON-LD as a linked graph (WebSite, WebPage, BreadcrumbList, BlogPosting…) when metatags.data is enabled: don't add favicon links or a separate JSON-LD/breadcrumb schema. Ship assets/favicon.png (or .svg) instead.layouts.autoescape: false): {{ page.content }} needs no |raw, but escape values printed in attributes (alt="{{ page.title|e('html_attr') }}"), and don't rely on autoescaping for user-provided text.partials/paginator.html.twig, partials/navigation.html.twig (expects a menu variable, and optionally page to mark the current entry with aria-current: {menu: site.menus.main, page: page}), partials/breadcrumb.html.twig, partials/languages.html.twig, partials/theme-selector.html.twig._default/page.html.twig, keep the code blocks styled, e.g. <style>{{ include('partials/highlight.css.twig') }}</style> when config.pages.body.highlight is enabled, or ship CSS for both engines' classes (hljs-* for highlightjs, hl-* for tempest, see pages.body.highlight.engine).<a class="heading-anchor"> link added to h2/h3 headings (see , e.g. a on hover) and use the attribute of code blocks (e.g. a language label).Extend with a list of templates so a site-level override wins over the theme default:
{# layouts/blog/page.html.twig #}
{% extends ['page.html.twig', '_default/page.html.twig'] %}
{% block content %}
<article class="post">
<h1>{{ page.title }}</h1>
{{ page.content }}
</article>
{{- include('partials/post-meta.html.twig') }}
{%- endblock content %}
List layout idiom (set the pages variable before extends):
{# layouts/_default/list.html.twig #}
{% set pages = site.pages.showable %}
{% if page.pages is defined %}
{% set pages = page.pages %}
{% endif %}
{% if page.paginator.pages is defined %}
{% set pages = page.paginator.pages %}
{% endif %}
{% extends ['page.html.twig', '_default/page.html.twig'] %}
{% block content %}
<ul class="posts">
{%- for post in pages %}
{%- include 'partials/post-item.html.twig' with {post} only %}
{%- endfor %}
</ul>
{{- include('partials/paginator.html.twig') }}
{%- endblock content %}
Section alias (e.g. reuse the blog list for the section fallback):
{% extends 'blog/list.html.twig' %}
To map a whole section to another section's layouts, the site (or the theme config) can use layouts.sections (e.g. layouts: {sections: {news: blog}}).
Remember the lookup rules when naming layouts (see the cecil skill, "Lookup Rules"): <section>/index, <section>/page, <section>/list, section/<section>, parent sections, _default/section, index/home, taxonomy/<plural> (vocabulary), taxonomy/<plural>/<term> and taxonomy/<singular> (terms), term, vocabulary, _default/*, with optional language variants (page.html.fr.twig). For non-HTML outputs, the file name is <layout>.<format>.twig (e.g. list.rss.twig, page.webmanifest.twig).
Non-HTML built-ins a theme may override: feeds (_default/list.atom.twig, list.rss.twig, list.jsonfeed.twig, all extending extended/feed.twig), their XSL stylesheets (_default/feed.xsl.twig, _default/sitemap.xsl.twig), _default/sitemap.xml.twig, _default/robots.txt.twig, _default/home.llms.twig, the *.markdown.twig and *.json.twig outputs, _default/404.html.twig and _default/redirect.html.twig. Override them only when needed: they receive Cecil fixes and features.
Put processed files in assets/ and reference them with asset():
{# bundle several CSS files into one #}
{{ html(asset(['css/poole.css', 'css/syntax.css', 'css/hyde.css'])) }}
{# compile Sass and inline it #}
<style>{{ asset('sass/<name>.scss')|inline }}</style>
{# remote asset, downloaded at build time #}
{{ html(asset('https://cdn.jsdelivr.net/npm/lib/dist/lib.min.js', {filename: 'lib.min.js', minify: false}), {defer: ''}) }}
{# responsive image #}
{{ html(asset(post.image), {alt: post.title}, {responsive: true, formats: ['webp']}) }}
{# optional asset #}
{% set logo = asset(site.logo|default('logo.svg'), {ignore_missing: true}) %}
{% if not logo.missing %}{{ html(logo, {alt: site.title}) }}{% endif %}
{# small inline CSS/JS #}
<style>{% apply minify_css %}.hero { color: red; }{% endapply %}</style>
html() function (the |html filter is deprecated).static/ for files that must keep their name and not be processed: web fonts, downloads, etc. Link them with url() (favicons are already linked by metatags). Don't ship a static/robots.txt: robots.txt is a built-in default page (custom rules go in a pages/robots.md page of the site).assets.compile.variables in the theme config.yml (e.g. assets: {compile: {variables: {primary: "#0d6efd"}}}); Sass import paths (assets.compile.import, [sass, scss, node_modules] by default) are resolved in the assets/ and static/ directories of the site and of the themes, and next to the compiled file.assets.minify, assets.fingerprint) rather than forcing them in templates.assets/ are not copied to the output (only static/ is), and *.scss is already excluded by default: no static.exclude is needed.assets/styles.css) and provide build scripts (see "Packaging").<nav>
<ul>
{%- for entry in site.menus.main|sort_by_weight %}
<li{% if url(entry.url) == url(page) %} class="active"{% endif %}><a href="{{ url(entry.url) }}">{{ entry.name }}</a></li>
{%- endfor %}
</ul>
</nav>
Always build links with url() (pages, menu entries, paths, assets), never hardcode site.baseurl.
Use the external test to detect links outside the site (e.g. {% if entry is external %} rel="noopener" target="_blank"{% endif %}), rather than matching http.
Link to the Cecil website with the cecil global variable, never a hardcoded https://cecil.app: cecil.url is already absolute (it includes the version as anchor), so don't pass it to url(). cecil.poweredby (Cecil v<version>) and cecil.version are available for the label:
{% trans with {'%cecil%': '<a href="' ~ cecil.url ~ '">Cecil</a>'} %}Powered by %cecil%{% endtrans %}
<a href="{{ cecil.url }}">{{ cecil.poweredby }}</a>
Filter collections: site.pages.showable|filter_by('section', 'blog')|sort_by_date|slice(0, 5).
Tags links: url('tags/' ~ tag|slugify) or iterate site.taxonomies.tags.
Get a specific page: site.page('about').
Wrap every UI string so the theme is translatable:
{% trans %}Read more{% endtrans %}
{% trans with {'%title%': site.title} %}%title% on GitHub{% endtrans %}
{{ 'You are offline'|trans }}
Provide at least one translation file, keyed by the source string:
# translations/messages.fr.yml
"Read more": "Lire la suite"
"%title% on GitHub": "%title% sur GitHub"
messages.<locale>.<ext> (yml/yaml, or compiled mo; .po files are not loaded), where <locale> is the language locale (fr_FR) or its first two letters (fr).php cecil.phar util:translations:extract --locale=fr --save --theme=<name>: the file is written to the site translations/ directory (messages.fr.yaml), move it into themes/<name>/translations/.No automatic injection mechanism exists: a component theme plugs into a site through generated pages and output formats, partials to include, macros, section-specific layouts, front matter blocks or Twig components. Official component themes exist (FlexSearch, PWA, dark mode toggle, Open Graph image, etc.): ask the user before installing one. Read references/component-themes.md for the patterns and the official component themes.
A theme is published as a Composer package (composer.json with type cecil-theme). Read references/packaging.md for the files to provide.
config.yml (not .yaml) with theme options under a <name>: namespacelayouts/_default/ (including home, term, vocabulary and 404 to override the built-ins), children extend ['page.html.twig', '_default/page.html.twig'], base layout defines a content blockpartials/metatags.html.twig included in every HTML base layout <head>, with no duplicated <title>/meta tags (unless the user declined it)paginator, navigation, breadcrumb…)url(), all processed files with asset(){{ cecil.url }} (not a hardcoded URL, not wrapped in url())?? or |default(); ?? for options that can be set to false, '' or 0 with a truthy fallback (never |default(true))trans, at least one translations/messages.<locale>.ymlcomposer.json with "type": "cecil-theme", extra.cecil.theme-name and "cecil/theme-installer": "^2.1"Theme "<name>" not found: the folder must be themes/<name>/ (matching the theme name resolved by the installer: extra.cecil.theme-name, extra.name or the package name) and contain layouts/ or config.yml.vendor/ instead of themes/: the project doesn't allow the plugin; add "cecil/theme-installer": true to config.allow-plugins in the project's composer.json, then reinstall.The ".../themes/<name>/layouts" directory does not exist: the theme has a config.yml but no layouts/ directory; add one, even empty.layouts/ file with the same path, or any file (site, theme or built-in) matching a higher-priority lookup name, wins (e.g. the built-in _default/home.html.twig before the theme _default/list.html.twig); check with php cecil.phar build -vv, or remove the site layout.site.data.*): the site has no data/ directory; create one.output.pagetypeformats.homepage) is added to the theme list, so the values required by the theme are kept; the site can only remove one with a map of booleans (e.g. homepage: {atom: false}).Theme "<name>" (required by theme "<other>") not found: the theme is required by the config.yml of another theme but is not installed in themes/<name>/; install it (composer require), and add it to the require section of the requiring theme's composer.json.config.yml of a theme required by another theme is not loaded; update Cecil, or list the theme explicitly in the site theme key.asset() are relative to assets/ (or static/) of the site or theme, without the directory prefix.messages.<locale> or (e.g. → or ); the translations cache is refreshed when a file is updated or removed, but not when a new one is added: run .theme): https://cecil.app/documentation/configuration/site/#themeCreate, structure and package themes for Cecil (visual themes and component themes), following the conventions of the official Cecilapp/theme-* repositories.
---name: cecil-themedescription: Create, structure and package themes for Cecil (visual themes and component themes), following the conventions…---# skills/cecil-theme/SKILL.md常见问题
从发布者处下载 skills/cecil-theme/SKILL.md,或复制路径后打开仓库。PlugMCP 只收录该技能,不托管文件。
发布者将它存放在 https://github.com/Cecilapp/Cecil。
Claude、Cursor、Codex 和 Grok Build 可以读取你从发布者仓库添加的 SKILL.md。在聊天中发送技能的 GitHub 文件夹链接,Grok Bot 就会安装它。
extensions.subscribersextensions.pluginsCecil\Plugin\AbstractPluginpages.body.anchors#data-lang<pre>:::<type> notes render as <aside class="note note-<type>">, and the built-in tabs, code-group, steps, accordion and cards types as <div class="note note-<type>"> (no JavaScript); style these classes, and the items: .note-tab (tabs, code-group), .note-steps-list, .note-accordion-item (<details>), .note-cards-list. A theme can override or add partials/notes/<type>.html.twig, which only receives a note variable (no page or site).ignore_missing = true so the theme works whether they are installed or not.with_context = false) to partials that only need site/page.assets/<name>/, CSS classes and custom properties prefixed with <name>, technical generated pages with excluded: true and serviceworker.precache: falsedemo/ + link.php) with php cecil.phar build -v and php cecil.phar serve, without a site layouts/ directorymessages.<first two letters of the locale>fr_FRmessages.fr_FR.ymlmessages.fr.ymlphp cecil.phar cache:clear:translationsDeprecated configuration option(s) in …: the theme's config.yml uses a renamed or removed option (see config/deprecated.php), which makes the build fail for every site using the theme; apply the snippet given in the error message.php cecil.phar doctor to check theme configuration.