Heathen Engineering

Heathen’s SKILL.md Files

Introduction #

SKILL.md is Heathen’s answer to a simple problem: any coding agent, Claude Code, Cursor, Copilot, or anything else, should be able to ramp up on a Heathen tool from a file sitting right next to the code, without needing web access or a human to explain it. It’s a README written for an agent instead of a person.

Best Practices #

  • Tell your agent to read it first, explicitly. Don’t assume it’ll go looking on its own before it starts writing code against a package it hasn’t seen before.
  • Treat it as a starting point, not the full picture. SKILL.md is dense reference, not exhaustive documentation, the KB and the real source are still there for anything it doesn’t cover.
  • Expect one per layer, not just one per product. A single project can have an ecosystem-level, an engine-level, and several product-level SKILL.md files all relevant at once, see below.

The three layers #

SKILL.md files exist at three levels, each pointing to its neighbors so an agent can navigate up or down as it needs more or less context:

  • Ecosystem. One file describing Heathen’s tools as a whole, the Foundation/Toolkit split, and how the pieces relate.
  • Engine. One per engine (Unity, Unreal, Godot, O3DE), covering what’s specific to working with Heathen’s tools in that engine.
  • Product. One per product, the file that actually ships inside the installed package, and the one your agent will run into first in a real project.

Where they live #

Product-level files ship inside the installed product itself, not just in a dev repo somewhere your agent can’t see. Placement depends on the engine:

  • Unity: at the root of the UPM package folder.
  • Unreal: at the root of the copied Plugins folder.
  • Godot: at the root of the copied res://addons folder.
  • O3DE: at the root of the registered Gem folder.

Every standalone FOSS Foundation repo also carries a copy at its own repo root, so it’s visible even if you’re browsing the source directly rather than working from an installed package.

What it deliberately won’t tell you #

SKILL.md files are user-facing orientation only, they describe the product you’re using, not how Heathen builds or documents it internally. If you’re looking for that level of detail, it isn’t there on purpose, the file’s job is to get your agent productive on the tool in front of it, nothing more.

Rate This Article!

Contents