Catalog Authoring
Write catalog sources in YAML and project them to the files that coding agents load.
Steps
- Start a skill with
basicly catalog new skill <slug>, or a fragment withbasicly catalog new fragment <id> --category <category>. Write an output style by hand, as sources shows. Find an existing skill withbasicly catalog list skill. - Edit the YAML source, never the projected file.
- Run
basicly catalog lint. - Build and check the projection:
basicly buildthenbasicly checkfor a fragment,basicly skills-buildthenbasicly skills-checkfor a skill,basicly styles-buildthenbasicly styles-checkfor an output style. - Run
basicly catalog verifybefore a catalog commit. - Read each projected file back where the agent reads it, as projection shows.
Rules
- Never give a source a file name that an agent loads. Agents load
SKILL.md,AGENTS.md,CLAUDE.md,*.instructions.md,*.mdcandGEMINI.mdby file name, so a source isskill.yaml,<id>.fragment.yamlorstyle.yaml. - Apply the deletion test to each bullet. If its removal causes no mistake, leave it out.
- Tag a source with
technologiesonly when it is useless outside that technology. An untagged source ships everywhere. - Keep local sources out of
.basicly/core/in a consumer repository.basicly install --forceoverwrites a hand-edited core file. Put a fragment in.basicly-local/fragments/. - Put a Claude-only prompt, command or runbook in
.claude/*.md. No catalog source projects it. - Add no copy under
.github/instructions/. Copilot then loads the same rule twice. Prefer a skill to a prompt file, and put a custom agent in.github/agents/*.agent.md.
Read when needed
- Before creating or changing a source type, read sources for its schema, placement, overlay and host projection.
- Before composing or delivering guidance, read projection for wording, checks and effective-host readback.
- Done when the source and its projected files agree, local overlays are kept, and you report each check you ran.