agentleFS
zauberzeugzauberzeug/game-of-cards/.claude/skills/create-card/SKILL.md

create-card

Skill7 starsChanged 6 months agoMITView on GitHub

File a new card with frontmatter and a DoD scaffold BEFORE implementation — the body is the briefing the next reader needs to act cold. AUTO-INVOKE on "let's do X", "implement Y", "fix Z", a described bug, a requested feature, or ANY new persistent work item.

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 2 are distinctive, and 9 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 9

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If any ! block below shows goc: command not found, Permission for this action has been denied, or no such file or directory: …

    line 13
  2. Very specific:

    Read the slug aloud — avoid word stutter, colloquial back-half clauses, and family-shape mismatch (reference.md § Title quality).

    line 52
  3. Very specific:

    Verify the title is free: run goc show <your-title> yourself — ERROR: ...

    line 55
  4. Very specific:

    If a disproved rebuttal exists for this hypothesis, re-read it before filing.

    line 75
  5. Very specific:

    When in doubt between decision and session: if a ## Decision required section would under-serve the question (options not yet well-scoped, …

    line 94
  6. Very specific:

    If a substantive decision sits at the card's core, consult the consuming repo's rubric *before* defaulting to decision:

    line 98
  7. Very specific:

    If the rubric answers cleanly with a principle citation AND primary-source backing, scaffold with --gate none and pre-write a ## Decision …

    line 103
  8. Distinctive:

    Consider a sibling artifact file for gated cards (Step 7).

    line 166
  9. Very specific:

    Run via uv run python deck/<title>/reproduce.py.

    line 206
  10. Very specific:

    When markdown can't express the content — colored option grids, state diagrams, interactive decision forms, screenshots — ship the artifact …

    line 215
  11. Distinctive:

    Commit the filing per the consuming repo's checks and GoC hooks.

    line 228

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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

When to invoke

Invoke when the user says "let's do X", "implement Y", "fix Z", describes a bug, requests a feature, or initiates ANY persistent work item. Title must be user-facing, descriptive, PO-readable (not engineer's jargon). reproduce.py (Step 6) is hand-authored for bug-class cards, not scaffolded.

Preflight

If any ! block below shows goc: command not found, Permission for this action has been denied, or no such file or directory: .game-of-cards/deck/, stop and invoke Skill(kickoff) first. Kickoff finds the missing setup step (CLI not installed, deck not scaffolded); a denied goc call goes to Skill(claude-kickoff) on Claude Code. Re-invoke this skill only after kickoff completes.

File a new card

A card is a self-contained briefing for the next reader — human or agent — written so the work can be picked up cold: its own evidence, its own framing, its own closure contract (the DoD). Scaffold a deck/<title>/ dir with valid frontmatter, an empty log.md, and a placeholder DoD that Skill(finish-card) will refuse to satisfy until you write real criteria. The CLI guarantees frontmatter validity; the body is on you.

Edge cases live in reference.md (sibling file in this skill's directory) — read the named section only when the situation applies:

Situationreference.md section
Slug reads badly aloudTitle quality
A parked card may already hold this findingDedup against parked cards
The card coordinates other cardsEdge direction for coordinating cards
A substantive decision at the card's coreRubric-derived decisions
Body needs diagrams / matrices / formsRich artifact files
Draft-flag lifecycle detailsDraft contract
Reachability path for parser/emitter defectsReachability
Why cards are written this wayRationale

User argument: $ARGUMENTS

Step 1 — confirm the title

Slug pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$. Short, hyphenated, the observable problem, PO-readable — e.g. csv-export-button-truncates-rows-over-10000.

goc new enforces a title-antipattern guard (see Skill(card-schema) "Title antipatterns"): it rejects rN rounds, path-N / phase-N steps, bug-N numbering, _md_ / _py_ infixes, camelCase, and math symbols, suggesting a rephrasing from the observable problem. --allow-jargon only for migration tools. Read the slug aloud — avoid word stutter, colloquial back-half clauses, and family-shape mismatch (reference.md § Title quality).

Verify the title is free: run goc show <your-title> yourself — ERROR: ... not found means safe.

Step 2 — dedup against open / done / disproved queues

Same root cause as an existing card = supporting evidence on that card's body + a log.md appendage on the existing entry, NOT a new filing. Grep for the candidate's identifying string yourself, e.g. goc --status all | grep -i <fragment>.

Titles are not enough. Duplicates hide in the gated backlog: parked cards name your symbol in the body, and nothing re-reads them (reference.md § Dedup against parked cards). A gated hit is a card to strengthen, not to file beside.

grep -rli '<symbol-or-phrase>' .game-of-cards/deck/*/README.md
goc triage                 # gated cards, oldest first

If a disproved rebuttal exists for this hypothesis, re-read it before filing. Re-promote only if git log -p -- <cited-file> shows the cited code has changed since the disproved entry's date.

Step 3 — pick the gate

The CLI default is decision — the fallback for findings whose fix path genuinely needs a human pick. When the work shape makes the right gate clear, set it explicitly:

  • --gate none — fully mechanical: sed-style rename, stale-reference patch, single-line constant correction. Autonomous-loop-safe.
  • --gate decision — two or more credible fix paths and a human must pick. You MUST then write the ## Decision required body section (per Skill(card-schema) "Decision-gate contract").
  • --gate session — research-impacting: framework derivation gap, mechanism choice between literature alternatives, sign convention, new named primitive, default anchored to a paper / axiom.

When in doubt between decision and session: if a ## Decision required section would under-serve the question (options not yet well-scoped, or picking needs new evidence), use session.

If a substantive decision sits at the card's core, consult the consuming repo's rubric before defaulting to decision:

!cat .game-of-cards/hooks/create-card.md 2>/dev/null || true

If the rubric answers cleanly with a principle citation AND primary-source backing, scaffold with --gate none and pre-write a ## Decision (rubric-derived) body section (choice, principle, citation). Reserve human gates for questions the rubric cannot answer (reference.md § Rubric-derived decisions).

Step 4 — scaffold via the CLI

goc new <title> \
  --summary "<what + why>" \
  --contribution <high|medium|low> \
  --gate <none|decision|session> \
  --tag bug \
  --tag <area-tag> \
  --advances <target-title> \
  --advanced-by <parent-title> \
  --commit

Creates deck/<title>/README.md (valid flat frontmatter, placeholder - [ ] (replace with real criteria) DoD) plus an empty log.md. Tags must come from the canonical set — the CLI rejects unknowns; project-local tags register in .game-of-cards/canonical-tags.md (see Skill(card-schema) "Adding new tags").

  • Known value-flow at filing time → pass --advances / --advanced-by AND --commit so both edge endpoints land in one atomic commit (without --commit, an explicit-pathspec commit of just the new directory ships a half-edge). The goc new + goc advance two-step is the fallback for edges discovered later.
  • Coordinating card? Aggregation epic (closes when its children close) → child.advances: [epic]. Governing cluster (closes when decided) → shared tag, NO edge. Never epic.advances: [children] (BACKWARDS_EPIC_EDGE). Full reasoning: reference.md § Edge direction for coordinating cards.
  • The scaffold is born draft: true — hidden from queues until authored (Steps 5–7). Claiming or closing clears the flag; goc publish <title> releases an authored-but-unclaimed card (reference.md § Draft contract). All three need a summary: (Step 5).

Step 5 — write the body (the dashboard)

The README body is the card's dashboard: a snapshot of latest knowledge, rewritten in place as understanding evolves. Do NOT append "Latest finding (DATE)" blocks — history belongs in log.md (see Skill(card-schema) "What goes where"). Replace the placeholder with:

  • Title (H1) — one-line description.
  • Summary — frontmatter summary: (≤ 3 sentences, what + why) so triage views can scan without opening; goc validate requires it once the card leaves draft.
  • Location — file:line (bug-class) or doc/section (doc-class).
  • What's broken — prose with quoted code AND quoted contradicted doc/comment; the reader must see the conflict.
  • Empirical evidence — reproduce.py output verbatim (Step 6).
  • Why it matters — connect to a real symptom; cross-link cards as [<title>](../<title>/). For parser / emitter / storage-layer defects, name the reachability path that produces the offending input (reference.md § Reachability).
  • Fix — concrete change with file:line. Do NOT apply the fix. For decision gates this collapses into ## Decision required. Consider a sibling artifact file for gated cards (Step 7).
  • Refine the DoD — each box a contract, prefixed with its method class (see Skill(card-schema) "DoD method tags"); prefer TDD: whenever a closed-form expected value exists:

    definition_of_done: |
      - [ ] TDD: reproduce.py exits zero (defect no longer fires)
      - [ ] TDD: <specific assertion or metric the fix must satisfy>
      - [ ] EMPIRICAL: <experiment run, verdict recorded in log.md either way>
      - [ ] MECHANICAL: <doc/config edit landed and reads correctly>
      - [ ] PROCESS: <agreement recorded, parent advanced_by updated>

Each later round of work rewrites the dashboard and appends a log.md journal entry (what changed, why).

Step 6 — write reproduce.py (bug-class only)

For bug / measurement / regression cards, ship a deck/<title>/reproduce.py that, on a clean checkout, prints output an outside reader would accept as proof. Find the repo root holding .game-of-cards/ with the parent-walk pattern — never parents[N] with a fixed N:

import sys
from pathlib import Path

def _repo_root() -> Path:
    p = Path(__file__).resolve().parent
    while p != p.parent:
        if (p / ".game-of-cards").is_dir():
            return p
        p = p.parent
    raise RuntimeError(".game-of-cards/ not found")

sys.path.insert(0, str(_repo_root()))

Run via uv run python deck/<title>/reproduce.py; paste the output verbatim into "Empirical evidence".

For plausible-but-unreproduced hypotheses, add --tag unverified and document the falsifying-test recipe in the body; drop the tag once a working reproduce.py lands.

Step 7 — rich artifact files (optional, any card class)

When markdown can't express the content — colored option grids, state diagrams, interactive decision forms, screenshots — ship the artifact as a sibling file in the card directory and link it from the README ([See the matrix](comparison-matrix.html)). Sibling files are opaque to the engine. Bundle shape, use/skip criteria: reference.md § Rich artifact files.

Cross-references

  • reference.md (this skill's directory) — edge cases routed above.
  • Skill(card-schema) — field semantics, enums, canonical tags.
  • Skill(scan-deck) — dedup queries; Skill(advance-card) — if the body reveals a different gate than scaffolded.
  • Commit the filing per the consuming repo's checks and GoC hooks.

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.