Modifying CLI Manifest Schema
Developmentmodifying-cli-manifest-schemaModifying CLI Manifest Schema is an Agent Skill for development published in the golemcloud/golem repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Adding or changing application manifest JSON schema versions and aligning CLI schema references.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/golemcloud/golem/blob/HEAD/.agents/skills/modifying-cli-manifest-schema/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/modifying-cli-manifest-schema, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Skill: modifying-cli-manifest-schema
Use this skill when changing the Golem application manifest JSON schema under
cli/schema.golem.cloud/app/golem/ or when adding/removing manifest fields in
cli/golem-cli that must be reflected in schema validation and generated
template references.
Do not use this skill for the structured command output schema under
cli/golem-cli/command-output-schema/command-output.schema.json. For CliOutput
types, to_cli_output_value, or command-output schema generators, use
modifying-cli-output-schema instead.
Core Rules
- Do not edit the currently published schema version in place for feature work.
- Create exactly one new schema version directory per PR.
- Copy the latest schema directory as the starting point for the new version.
- Apply schema changes only in the new version directory.
- Update the CLI to point to the new schema version when the new schema should become the default for generated manifests and validation.
Important Terminology
- Manifest version: the version of the YAML document itself, exposed as
sdk::MANIFESTincli/golem-cli/src/versions.rs. - Manifest schema version: the version of the JSON schema under
cli/schema.golem.cloud/app/golem/<version>/golem.schema.json, exposed viamanifest_schema_version!()incli/golem-cli/src/versions.rs.
These are NOT the same concept and do not have to move together.
Examples:
- A schema-only bug fix may create
1.5.1.1without changing the manifest version. - A new development-line schema may create
1.6.0-dev.1while the manifest version is a release-line version such as1.6.0.
Choosing the New Version
Use project/release direction from the user or surrounding work. If not stated:
- Use a new
-dev.Nschema version for in-progress development line work. - Use a patch-like schema version only for schema-only fixes intended to refine an already established line.
Schema versions are published to schema hosting during development, so -dev.N
versions are useful and expected. Manifest document versions are release-line
versions and may accumulate multiple in-tree changes before release.
For this repository, the user has stated the convention that we usually create one new schema version per PR.
Workflow
- Identify the current latest schema directory under
cli/schema.golem.cloud/app/golem/. - Create the requested new directory by copying the latest schema version.
- Modify only the new copied schema.
- Update
cli/golem-cli/src/versions.rscarefully:sdk::MANIFESTonly if the YAML document version itself should change.manifest_schema_version!()to the new schema version if the CLI should validate against and emit references to the new schema by default.- If
sdk::MANIFESTchanges, update manifest-version compatibility policy and tests incli/golem-cli/src/app/manifest_version.rs.
- Check other schema-version consumers, especially:
cli/golem-cli/src/lib.rscli/golem-cli/src/app/template/snippet.rs- tests containing embedded
$schemareferences
- Update tests as needed.
- Run focused validation/build/tests.
Things To Watch
- Do not mass-edit old schema versions unless the user explicitly wants a backfill.
- Do not assume
sdk::MANIFESTandmanifest_schema_version!()should always match. - Do not bump
sdk::MANIFESTwithout checking whether existing manifest versions should remain compatible. - When introducing a new field or enum value, ensure both serde parsing and JSON schema validation agree.
- If the CLI emits manifest templates/snippets, make sure they reference the new schema version.
Useful Files
cli/golem-cli/src/versions.rscli/golem-cli/src/lib.rscli/golem-cli/src/app/template/snippet.rscli/golem-cli/src/model/app_raw.rscli/schema.golem.cloud/app/golem/*/golem.schema.json
Verification Checklist
- New schema directory exists and was copied from the intended predecessor.
- The new schema validates the new manifest feature.
- Old schema directories were not modified unless explicitly intended.
- CLI version constants were updated correctly.
cargo check -p golem-clipasses.- Relevant tests pass.