Theme
Aa
← man.tcos.us gopher root · man.tcos.us
lu: · ·
HEE-GEN-SKILLS(1)                  HEE Tools                  HEE-GEN-SKILLS(1)

NAME
       hee-gen-skills - hee-gen-skills command

SYNOPSIS
              hee-gen-skills [--write] [--out DIR]
              hee-gen-skills help

DESCRIPTION
              hee-gen-skills: generate agent-readable SKILL.md from Skill objects.

              Real trigger (2026-09-02, Spencer): "do we have any skill objects yet? we
              should by now. want to use them to convert into skills file that agents can
              read (downstream by design)."

              The downstream already existed, built once by hand:

                  hee/skills/ratify-contract-v1.skill.yaml     the Skill object
                  .claude/skills/ratify-contract/SKILL.md      the agent-readable form

              That SKILL.md even names the relationship -- "source of truth is
              hee/skills/ratify-contract-v1.skill.yaml. This packages that same procedure
              so it is discoverable without already knowing the doctrine file exists."

              What was missing is the generator. A hand-kept restatement drifts the moment
              either side changes, and this org has hit that exact failure three times in
              one day: bootstrap.mk help, hee-ticket ACTIONS, and the glossary. One Skill
              exists today, so writing this now costs little; at ten it would be a
              migration.

              ## Same principle as hee-gen-manpages, different source

              Pure extraction, deterministic from the object, never hand-authored at the
              destination. Re-run any time a Skill changes.

              ## Why a sibling rather than an extension

              hee-gen-manpages is the closest existing tool and the right conceptual
              home, but its name says manpages. Teaching it to emit SKILL.md would make
              that name inaccurate, which is the same "field that claims something it
              does not do" defect this org has been filing against other tools all day.
              This lands in the established `gen-*` namespace instead of inventing a new
              concept. Flagged for review rather than decided silently.

                Reads every kind: Skill object under hee/skills/ and renders one
                SKILL.md per skill into .claude/skills/<name>/.

                Dry run by default. --write is required to touch the filesystem, matching
                hee-gen-manpages, so an accidental invocation cannot rewrite agent
                instructions.

EXIT STATUS
              0 OK        generated, or dry run completed with no differences
              1 WARNING   dry run found differences that --write would apply
              2 CRITICAL  a Skill object is malformed or unreadable
              3 UNKNOWN   pyyaml missing, or no hee/skills directory

EXAMPLES
              $ hee gen-skills   # ci

              A bare run is a dry run and writes nothing (exit 0 unchanged, 1 if --write
              would apply differences); --write rewrites .claude/skills/ and is unmarked.

                                                              HEE-GEN-SKILLS(1)