Skip to content
Skills Library
AI & agents · Building & coding

create-runfile

/create-runfile

Use when authoring or repairing Kilroy run config YAML/JSON files, including DOT-to-provider backend alignment and runtime policy defaults.

Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when authoring or repairing Kilroy run config YAML/JSON files, including DOT-to-provider backend alignment and runtime policy defaults.

Original author description

Use when authoring or repairing Kilroy run config YAML/JSON files, including DOT-to-provider backend alignment and runtime policy defaults.

How it works

  1. Scope
  2. Overview
  3. Workflow
  4. Non-Negotiable Guardrails
  5. References
Original SKILL.md headings · 103 lines, 679 words
SKILL.md preview
---
name: create-runfile
description: Use when authoring or repairing Kilroy run config YAML/JSON files, including DOT-to-provider backend alignment and runtime policy defaults.
---

# Create Runfile

## Scope

This skill owns run config authoring (`run.yaml` / `run.json`) for `kilroy attractor run` and `resume`.

In scope:
- Building config structure (`version: 1` schema).
- Aligning provider backends with DOT model/provider usage.
- Setting runtime, preflight, modeldb, git, and CXDB defaults.

Out of scope:
- DOT graph authoring and routing design. Use `create-dotfile` for graph work.

## Overview

Core principle:
- Keep execution policy in run config, not in DOT topology.
- Align run config with what the graph needs to execute now.
- Favor explicit, deterministic defaults over implicit behavior.

Default run-config source:
- `skills/create-runfile/reference_run_template.yaml`

## Workflow

1. Collect inputs.
- Read the target DOT graph and detect provider usage (`llm_provider` attrs and `model_stylesheet`).
- Capture user constraints for production/test mode and backend policy.

2. Choose run mode explicitly.
- Production mode: `llm.cli_profile: real` and no test-shim flags.
- Test mode: `llm.cli_profile: test_shim` with shim-compatible provider config.

3. Start from the template and fill required fields.
- Required: `version`, `repo.path`, `cxdb.binary_addr`, `cxdb.http_base_url`, `modeldb.openrouter_model_info_path`.
- Keep absolute paths for repo/modeldb/script entries.
- Emit only fields supported by `internal/attractor/engine/config.go`.
- Unknown keys are rejected at load time; do not emit unsupported keys.

4. Align providers with DOT.
- For every provider used by DOT, set `llm.providers.<provider>.backend` (`api` or `cli`).
- Do not edit DOT to force backend execution strategy.

4.5 Resolve model names deterministically when catalogs are unavailable.
- Model resolution order: user-specified model -> run snapshot/modeldb path -> `internal/attractor/modeldb/pinned/openrouter_models.json` -> `internal/attractor/modeldb/manual_models.yaml` -> `skills/shared/model_fallbacks.yaml`.
- Use `skills/shared/model_fallbacks.yaml` only as backup; never let backup entries override explicit user model/provider choices.
- Normalize known aliases through fallback mappings before emitting YAML (for example provider `zai`: `glm-5.0` -> `glm-5`).

5. Populate artifact_policy from skills/shared/profile_default_env.yaml.
- The engine applies only env overrides declared explicitly in the run config.
- Read `skills/shared/profile_default_env.yaml` for per-profile reference values.
- Emit all required env vars for each profile used by the DOT graph.
- Set `artifact_policy.checkpoint.exclude_globs` for checkpoint hygiene.
- Do not use deprecated `git.checkpoint_exclude_globs`.

5.5 Declare secrets the project needs at build/test time.
- If the project under construction needs API keys at test or build time (e.g. `GEMINI_API_KEY` for smoke tests that call a live LLM), declare them in `artifact_policy.env.overrides` so they pass through to the agent shell.
- The agent shell deny-lists env vars whose names contain `API_KEY`, `SECRET`, `TOKEN`, `PASSWORD`, or `CREDENTIAL` by default. Vars declared in `artifact_policy.env.overrides` bypass this deny list because they represent explicit operator intent.
- Store the actual secret values in a `.env` file at the repo root (gitignored). The engine loads `.env` at startup and declared override keys pick up the OS values automatically.
- Use an empty string as the override value — the engine substitutes the real value from the environment at resolve time:
  ```yaml
  artifact_policy:
    env:
      overrides:
        generic:
          GEMINI_API_KEY: ""   # value comes from .env / shell environment
  ```
- Never put actual secret values in the run config file.

6. Apply runtime defaults and safety guardrails.
- Set `git.run_branch_prefix`, `git.commit_per_node`, and `git.require_clean` intentionally.
- Keep `runtime_policy` explicit (`stage_timeout_ms`, `stall_timeout_ms`, retry cap).
- Enable `preflight.prompt_probes` and use a non-aggressive timeout baseline for real-provider runs.

7. Preserve local-run robustness.
- In this repo, keep `cxdb.autostart` launcher wiring when generating local CXDB configs.
- Keep artifact/checkpoint hygiene settings where relevant (for example managed tool-cache roots).

8. Validate alignment before handoff.
- Confirm every DOT provider has a run-config backend entry.
- Confirm mode consistency (`real` vs `test_shim`) with intended command flags.
- Confirm config has no unresolved placeholder paths.
- If graph prompts consume scratch artifacts, require run-scoped paths (`.ai/runs/$KILROY_RUN_ID/...`); root `.ai` is not implicitly ingested.

## Non-Negotiable Guardrails

- Backend policy lives in run config; do not encode it in DOT structure.
- Do not omit providers that are referenced by the graph.
- Do not use fragile preflight probe timeouts for real-provider runs.
- Do not emit local CXDB configs without `cxdb.autostart` wiring in this repository context.
- Do not emit unsupported keys (for example: `runtime_robustness`, `provider_capability_constraints`).

## References

- `docs/strongdm/attractor/attractor-spec.md`
- `docs/strongdm/attractor/unified-llm-spec.md`
- `README.md`
- `skills/create-runfile/reference_run_template.yaml`
- `skills/shared/profile_default_env.yaml`
- `skills/shared/model_fallbacks.yaml`
Files in this package (3)
  • .origin 1 KB
  • SKILL.md 5 KB
  • reference_run_template.yaml 3 KB

Versions

The database has no other skills named create-runfile.

Database snapshot: 13.11.2026 · package version a5a562eb2109 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100create-dotfile
    Use when authoring or repairing Kilroy Attractor DOT graphs from requirements, with template-first topology, routing guardrails, and validator-clean output.
  • 100release-kilroy
    Use when preparing a Kilroy release — writing release notes, tagging, and publishing via goreleaser on GitHub.
  • 100dotnet-runfile
    How to use the .NET 10 `dotnet run app.cs` feature. Use this skill when you need to run an existing single-file C# script, create a new C# script, run an ad-hoc C# script (e.g. to test the behavior of a C# snippet), or work on an existing C# script already in the repo. Covers…
  • 100dot-ai-request-dot-ai-feature
    Generate a feature request prompt for another dot-ai project. Use when you need a feature implemented in a sibling project (MCP server, controller, etc.) to unblock work in the current project.
  • 90doompi-author-profile
    Configure DoomPi profile discovery, personas, environment defaults, and precedence in profiles.yaml. Use when creating or changing personal or repository profiles. Do not use for config.yaml runtime settings, modes.yaml, or domains.yaml.
  • 95opencode-configure
    Configure OpenCode via opencode.json and AGENTS.md with deterministic provider setup, model selection, permission policies, formatter behavior, and environment variable handling; use when editing opencode configuration, setting model/provider defaults, tightening agent…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.