agentleFS
ljf06853ljf06853/keepfire/.claude/skills/card-schema/SKILL.md

card-schema

Skill1 starsChanged 4 months agoMITView on GitHub

The recipe-card Markdown and frontmatter format is a parser contract. Read this before changing card structure, headings, frontmatter fields, or the render/parse functions in src/store.ts — a mismatch silently corrupts every card in the user's library.

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. zauberzeug/game-of-cards★ 7same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository3 other files it gives its agents.

The file

Files
SKILL.md

Recipe cards are stored as one Markdown file per recipe under $KEEPFIRE_HOME/cards/ (default ~/.keepfire/cards/). The format is not a display detail — it is the on-disk database, and it is written and read by two hand-rolled functions that must agree exactly.

What must move in lockstep

Change any one of these and you must change all of them in the same edit:

  1. renderCardMarkdown in src/store.ts — writes the card.
  2. parseCardMarkdown in src/store.ts — reads it back, by regex-matching exact ## heading text.
  3. templates/card.md — the canonical shape shown to users and agents.
  4. The RecipeCard interface in src/types.ts.
  5. SKILL.md — if the change affects what agents are told to write, since agents can write cards directly when the CLI is absent.

Why a mismatch is dangerous, not just broken

rebuildIndex in src/store.ts wraps card parsing in a bare catch {} and skips anything that fails. So a renamed heading does not throw — it makes every existing card parse to empty or get silently dropped from the index. The user's library appears to lose recipes with no error. Any change here needs a test that round-trips a card through render → parse and asserts field-by-field equality, plus a check that existing cards on disk still parse.

Hard constraints

  • Headings are the contract. parseCardMarkdown matches exact heading strings (## Raw prompt, ## Skeleton, ## Constraints, ## Output contract, ## Why it worked, ## Anti-patterns, ## Notes). Read the current regexes before assuming the list; do not rename a heading without updating them.
  • raw_prompt and skeleton live inside ```text fences. The parser expects the fence. Prompt bodies can themselves contain backticks and code fences — if you change fence handling, test with a prompt that contains a nested fence.
  • Frontmatter must stay flat and inline. It is parsed by parseSimpleYaml, not a YAML library. It handles only key: value, inline [a, b] arrays, quoted strings, numbers, booleans, and null. Nested maps, block arrays, and multiline scalars will not parse. Adding a structured field means either keeping it flat or upgrading the parser (and then handling every card written by the old one).
  • Cards are user data that already exists on disk. A format change is a migration, not a refactor. Either keep the parser backward-compatible with cards written by prior versions, or ship an explicit migration path — keepfire reindex re-reads cards, it does not rewrite them.

Related invariants

  • improveCard derives the new id as `${parent.id}-v${nextVersion}`, so ids compound across generations (...-abcd-v2-v3). If you change the id scheme, existing parent/child links break.
  • index.json is derived state and can always be rebuilt from cards/*.md via rebuildIndex. The Markdown files are the source of truth — never make the index authoritative.

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.