| name | catalog-authoring |
| description | Author and improve basicly catalog sources — skills and fragments — in their YAML source format (never a discoverable .md), then project and verify them. Use when adding or editing a skill or fragment, building a catalog, or deciding where guidance should live (always-on fragment vs on-demand skill). |
Catalog Authoring
Scope
Owns authoring the two projected catalog content types — skills and
fragments — in their non-discoverable YAML source format, and projecting
them to the files coding agents actually load.
- A fragment is always-on guidance merged into the projected
CLAUDE.md,
AGENTS.md, and copilot-instructions.md (and, when scoped, into per-path
rules/instructions files). Keep it terse; point at commands, do not restate
mechanically-enforced rules.
- A skill is an on-demand runbook projected to
SKILL.md at the target
skill roots and loaded only when its description trigger matches.
The non-negotiable rule: sources are never named for discovery
Coding agents auto-discover context by filename/extension — SKILL.md,
AGENTS.md, CLAUDE.md, *.instructions.md, *.mdc, GEMINI.md. So catalog
sources are authored as YAML (skill.yaml, <id>.fragment.yaml) and the
discoverable .md is emitted only at the target roots by the projector. Never
add a SKILL.md or *.fragment.md under .basicly/core/; the catalog lint
gate rejects it.
Author a skill
- Scaffold:
basicly catalog new skill <slug> writes core/skills/<slug>/skill.yaml.
- Fill in
name (must equal the slug), a strong one-line description (the
discovery trigger — state when to use it), and the instructions body as
a | literal block scalar (markdown, indented two spaces).
- Project + verify:
basicly skills-build then basicly skills-check.
Author a fragment
- Scaffold:
basicly catalog new fragment <id> --category <category> writes
core/fragments/<category>/<id>.fragment.yaml.
- Fill in
id, description, category, applies_to (e.g. [all]), and the
body block scalar. Optional: priority, tags, status, title,
scope.paths (path-scoped rules), and the replaces/override overlay
fields.
- Project + verify:
basicly build then basicly check.
Technology scoping
A source that only makes sense for one stack or environment tool declares
technologies: [python] (skills, fragments, agents, and hooks all accept it);
an untagged source is universal and always ships. Values come from the
controlled vocabulary in basicly.schema.TECHNOLOGIES (stack tags plus
environment tools like zsh/tmux) — catalog lint rejects anything else.
Consumers narrow what they receive with basicly install --technologies ...;
don't tag a source unless it is genuinely useless outside that technology.
Phrasing rules for guidance bodies
Distilled from Anthropic's memory/best-practices docs and the curated
CLAUDE.md corpus (2026-07 research, epic basicly-84v):
- Concrete and verifiable beats vague intent: "use 2-space indentation" works,
"format code properly" does not.
- Put runnable commands in code fences — a fenced command is run verbatim, a
command described in prose gets improvised on.
- Pair every prohibition with the alternative the agent should take instead;
a bare "never X" leaves it stuck.
- Give a one-clause rationale so the rule generalizes beyond its literal case.
- Emphasis is a scarce resource: at most one
IMPORTANT-style marker per
projection, or every marker becomes invisible.
- Every rule should trace to a real incident, not a hypothetical one; the
quirks category exists for exactly those.
- Apply the deletion test before adding a bullet: would removing it cause the
agent to make mistakes? If not, leave it out.
YAML source shape
Every source starts with a # yaml-language-server: $schema=... header (editor
and agent validation against core/schemas/) and a schema_version. The prose
body is a literal block scalar so markdown round-trips losslessly:
schema_version: 1
name: my-skill
description: What it does and when to use it.
instructions: |
# My Skill
...
Gate
basicly catalog lint schema-validates every source, forbids .md-named
sources under the catalog, and forbids non-.yaml YAML there. It runs on
commit and in CI — run it locally before committing.
