| name | pkl-engineering |
| description | Pkl engineering for typed configuration contracts, expressions, amendments, evaluation, formatting, tests, projects, dependencies, rendering, and packages. Use when a repository contains `.pkl` modules or `PklProject`, or when configuration behavior should be modeled and enforced with Apple Pkl. |
Pkl Engineering
Treat Pkl as an evaluated configuration contract. Put invariants in Pkl types,
constraints, and amendment boundaries; then prove them by evaluating the real
entry modules and running their tests.
Apply concepts/type-safety/core.md as the shared semantic-design authority
when it is available. This skill owns Pkl-specific realization through closed
classes, literal unions, constrained aliases, typed amendments, evaluation, and
explicit evaluator capabilities; it does not redefine the cross-language rules.
Start From Live State
Resolve this skill directory, then use its façade rather than rebuilding Pkl
commands from prose:
<skill-dir>/scripts/pkl_agent --workspace <repo>
<skill-dir>/scripts/pkl_agent --workspace <repo> doctor
The no-argument view reports the executable, Pkl version, project and lock
presence, module/test counts, active evaluator policy, and useful next commands.
Stop on missing or unsupported; this façade supports Pkl >=0.32.0,<0.33.0.
Work the Contract
- Identify the configuration entry modules, their templates, consumers, and
external inputs. Do not assume every
.pkl file is directly evaluable.
- Encode required values and legal ranges in typed classes, type aliases, and
constraints. Use
amends when a consumer must retain a template's module
type and reject unknown members.
- Keep dynamic input at a boundary. Convert
Dynamic data to typed values
before downstream use, and allow environment or remote inputs explicitly.
- Run the narrowest façade operation that proves the change, then widen to
formatting, entry-module validation, project tests, and package verification
when those surfaces are affected.
- Report exact commands, exit status, evaluated modules, test aggregates, and
written artifacts. Evaluation is the enforcement gate; formatting and import
analysis are not substitutes for it.
Read language-and-modeling.md when
authoring schemas, constraints, amendments, generators, renderers, or tests.
Read projects-security-and-interop.md
when working with PklProject, dependencies, packages, environment/resources,
bindings, code generation, pkl run, or editor integrations.
Use the Façade
<skill-dir>/scripts/pkl_agent --workspace <repo> format check --all
<skill-dir>/scripts/pkl_agent --workspace <repo> imports <module>...
<skill-dir>/scripts/pkl_agent --workspace <repo> module validate <module>...
<skill-dir>/scripts/pkl_agent --workspace <repo> module inspect <module> --expression '<expression>'
<skill-dir>/scripts/pkl_agent --workspace <repo> test run [<test-module>...]
<skill-dir>/scripts/pkl_agent --workspace <repo> package verify [<project-dir>...]
<skill-dir>/scripts/pkl_agent --workspace <repo> format apply --all
<skill-dir>/scripts/pkl_agent --workspace <repo> module render <module> --format json --out <path>
<skill-dir>/scripts/pkl_agent --workspace <repo> test update [<test-module>...]
<skill-dir>/scripts/pkl_agent --workspace <repo> project resolve [<project-dir>...]
<skill-dir>/scripts/pkl_agent --workspace <repo> package fetch <package-uri>...
<skill-dir>/scripts/pkl_agent --workspace <repo> package build --out '<path-pattern>' [<project-dir>...]
Every command emits TOON on stdout. Diagnostics and large evaluated values are
bounded; use --full only when the preview is insufficient. Use --fields
where a list command offers additional columns. Exit 0 means success or an
idempotent no-op, 1 means the requested operation failed, and 2 means the
invocation was invalid.
The default agent-safe policy confines file access to the workspace, excludes
ambient environment resources and direct HTTPS module imports. Evaluation,
test, import, and download commands omit project evaluator settings; project
commands receive explicit root and allowlist flags so settings cannot widen
those boundaries. Add narrow
exceptions with --allow-env, --property, --allow-module, or
--allow-resource. Use --policy project only after inspecting and accepting
the repository's evaluator settings.
test run and package verify copy the workspace to a temporary sandbox so
snapshot or package side effects do not alter source. Mutating counterparts are
named explicitly. Arbitrary pkl run, external readers, publishing, LSP,
documentation generation, and language code generation remain advanced native
Pkl boundaries rather than hidden façade behavior.
Completion Criteria
- Every changed Pkl entry module evaluates successfully under the declared
policy, or the remaining failure is reported with its source location.
- Focused tests pass without unreviewed snapshot writes; intentional snapshot
updates are explicit and reviewed.
- Formatting, dependency-lock, rendered-output, and package claims cite the
corresponding façade result.
- No secret, environment resource, remote module, external reader, command
write, or package publication capability is enabled implicitly.
