agentleFS
Sign inStart free
niksavisniksavis/basicly/.claude/skills/catalog-authoring/SKILL.md

catalog-authoring

Skill2 starsChanged 6 days agoMITView on GitHub

Authors catalog sources in YAML (always-on fragments, output styles and the skill.yaml format) and projects them. Use before editing a generated file such as SKILL.md, CLAUDE.md or AGENTS.md, or when adding a fragment or output style.

1 other project uses a version of this, 1 of them edited.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 5 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Write catalog sources in YAML and project them to the files that coding agents load.

    line 9
  2. Very specific:

    Start a skill with basicly catalog new skill <slug>, or a fragment with basicly catalog new fragment <id> --category <category>.

    line 13
  3. Very specific:

    Write an output style by hand, as sources shows.

    line 14
  4. Very specific:

    Run basicly catalog verify before a catalog commit.

    line 19
  5. Distinctive:

    Read each projected file back where the agent reads it, as projection shows.

    line 20
  6. Distinctive:

    Apply the deletion test to each bullet: If its removal causes no mistake, leave it out.

    line 25
  7. Distinctive:

    Before creating or changing a source type, read sources for its schema, placement, overlay and host projection.

    line 33
  8. Distinctive:

    Before composing or delivering guidance, read projection for wording, checks and effective-host readback.

    line 34

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md
<!-- Generated by `basicly skills-build` from skill.yaml. Do not edit; edit the source. -->

Catalog Authoring

Write catalog sources in YAML and project them to the files that coding agents load.

Steps

  1. Start a skill with basicly catalog new skill <slug>, or a fragment with basicly catalog new fragment <id> --category <category>. Write an output style by hand, as sources shows. Find an existing skill with basicly catalog list skill.
  2. Edit the YAML source, never the projected file.
  3. Run basicly catalog lint.
  4. Build and check the projection: basicly build then basicly check for a fragment, basicly skills-build then basicly skills-check for a skill, basicly styles-build then basicly styles-check for an output style.
  5. Run basicly catalog verify before a catalog commit.
  6. 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, *.mdc and GEMINI.md by file name, so a source is skill.yaml, <id>.fragment.yaml or style.yaml.
  • Apply the deletion test to each bullet. If its removal causes no mistake, leave it out.
  • Tag a source with technologies only 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 --force overwrites 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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free