How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/cloudcannon/agent-skills --skill cloudcannon-configurationBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
CloudCannon configuration
This skill covers creating and customizing cloudcannon.config.yml, which tells CloudCannon how to understand and present the site's content, and .cloudcannon/initial-site-settings.json, which tells CloudCannon how to build the site.
When to use
- Creating or customizing
cloudcannon.config.ymlor.cloudcannon/initial-site-settings.json - Adding or changing Collections, Inputs, Structures, or Select Data
- A field is missing from the editor, or shows the wrong Input type
- Configuring Collection URLs so pages open in the Visual Editor
When not to use
- Adding editable regions to templates — that is `cloudcannon-visual-editing`. This skill configures the data behind them.
- MDX components or inline HTML in content — that is `cloudcannon-snippets`
- Running a full migration — start at `migrate-to-cloudcannon`, which enters this skill at Phase 2
- Operating on a hosted site — authenticating, listing or creating sites, reading and writing site files, triggering builds, or changing an existing site's build configuration is `cloudcannon-cli`. This skill decides what a configuration should say; that one runs the commands.
Do this before writing any configuration
bash
mkdir -p .cloudcannon/migration
curl -sL "https://github.com/cloudcannon/configuration-types/releases/latest/download/cloudcannon-config.latest.schema.json" \
-o .cloudcannon/migration/cloudcannon-config.latest.schema.json
curl -sL "https://github.com/cloudcannon/configuration-types/releases/latest/download/cloudcannon-initial-site-settings.schema.json" \
-o .cloudcannon/migration/cloudcannon-initial-site-settings.schema.jsonDo not proceed until both files exist. Training data hallucinates keys — the schemas are the only authoritative source.
Query recipes, the .gitignore rule, and the yaml-language-server rule are in json-schemas.md.
Check for an existing config in any format — cloudcannon.config.{yml,yaml,json,js,cjs,mjs}, not only .yml. If one exists, customize it, and run configure generate only with --dry-run, for reference; without --dry-run the CLI writes a second cloudcannon.config.yml beside it. If none exists, generate a baseline — see configuration.md § Generate a baseline.
Invalid keys
Check this table before writing config. These are keys agents have written that the schema doesn't have; the JSON schemas are authoritative.
| Wrong | Correct |
|---|---|
disable_url_preview: true | disable_url: true, which turns off the collection's output URL. |
output: false | Omit url and set disable_url: true, or use data_config instead of a collection. |
type: hidden | hidden: true beside type, on any input; hidden: "<query>" hides it conditionally. |
options.max on a text or textarea input | options.max_length, paired with min_length. |
_editables.text with block keys (bulletedlist, blockquote, format, table) | _editables.text is inline-only — see § `_editables` key-to-schema mapping. |
heading2: true, heading3: true | format: "p h1 h2 h3", a space-separated string — see § `_editables` key-to-schema mapping. |
options.collections: [team] | values: collections.team with value_key and preview — see inputs.md § Select values from a collection. |
options.structures: my_blocks | The full path, _structures.my_blocks — see structures.md § The four rules. |
timezone: "+10:00" | A top-level IANA name such as Australia/Melbourne, defaulting to Etc/UTC — see configuration.md § Review the generated config. |
paths.collections, paths.data | collections_config.<name>.path and data_config.<name>.path. |
paths.output | No such key: the build tool sets the output directory. paths holds asset directories only: static, uploads, uploads_filename, dam_uploads, dam_uploads_filename, dam_static, uploads_use_relative_path. |
A Material Symbols name outside the schema's enum, such as place | A name from the enum, such as location_on; an invalid name falls back to the default icon — check it with the icon recipe in json-schemas.md. |
Rules for every task
- Read the Verification checklist and the SSG's checklist before starting, so you know what to aim for.
- Finish only when every item in both checklists is verified.
- Give every field editors see an explicit
_inputsentry; type inference is a fallback — see configuration.md § Configure every field explicitly. - Run
npx @cloudcannon/cli validateafter every round of changes. When it flags a key, look up the correct one in § Invalid keys.
Contents
| File | Read when |
|---|---|
| configuration.md | Always, first, when writing config — the steps and the shared verification checklist. |
| json-schemas.md | Before writing any key, to check it exists in the schema. |
| cloudcannon-cli-guide.md | Generating the baseline step by step, or validating; the rest of the CLI is `cloudcannon-cli`. |
| schemas.md | Before adding a collection or writing its schemas — one collection can hold many schemas. |
| inputs.md | Before writing _inputs. |
| structures.md | Any field holds an array or an object, since editors can't add items without a structure. |
| collection-urls.md | Any collection produces pages, or a page fails to load in the Visual Editor. |
| build-commands.md | The build has generators or post-build steps. |
| configuration-gotchas.md | Looking up a cross-SSG pitfall while configuring. |
| troubleshooting.md | Configuration is already wrong and you're working from a symptom. |
SSG-specific: enter through the SSG's overview.md; it gives the reading order and lists every file for that SSG.
| The site uses | Start at |
|---|---|
| Astro | astro/overview.md |
| Hugo | hugo/overview.md |
| Eleventy | eleventy/overview.md |
Other skills:
| Skill | Read when |
|---|---|
| make-site-multilingual | Configuring a multilingual site: locale datasets, per-locale collections and locale-prefixed URLs. |
| cloudcannon-dev-server | The user wants to open the configured site in CloudCannon and try the collections and inputs. |
