Add rich-markdown-reports skill - #114
Draft
FadhlanR wants to merge 8 commits into
Draft
Conversation
Encourage the assistant to author .md files as rich Boxel markdown — embedding the live cards and files a report is about via BFM directives, and referencing real data instead of restating it — rather than writing plain text. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Workspace Sync Dry-Run CompleteDry-run completed successfully - no changes were made Dry-Run Results |
The skills-realm index.md is the pull-model entry point (the default skill in every AI room); the assistant reads its catalog and pulls a skill's SKILL.md on demand. A skill absent from the catalog is never discovered, so list rich-markdown-reports there and in the glossary per the repo's maintenance contract. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The card/file embeds only render when the markdown lives as a file in a realm; the same BFM typed into a chat reply stays raw text. State the requirement explicitly so the assistant writes the report to a realm rather than printing it in the conversation. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The assistant reads index.md but only pulled the skill when told to,
because its catalog line was descriptive rather than an instruction.
Add a Pre-flight "writing a .md file takes one more read" rule
(mirroring the host-commands rule), make the catalog line and the
SKILL description action-first ("read before writing any .md file"),
so the model reads the skill whenever a task will produce markdown —
even when the user never says "rich".
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The report content came out right, but the file was created with git-style conflict markers written as its body: the host's parser only recognizes Boxel's box markers, and source-code-editing (which defines them) is scoped to .gts/.json, so a .md write fell back to git-style markers. Route the write through source-code-editing's format, name the box markers explicitly, and warn against git-style markers and write-text-file. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
rich-markdown-reports was re-explaining SEARCH/REPLACE (box markers, new-file shape). Drop that and point to source-code-editing instead — one home for the write transport. For the delegation to resolve in the pull model, broaden source-code-editing so it's discoverable for any text file: its description and index.md catalog line were scoped to .gts/.json, which is why the model didn't consult it for a .md write. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Drop the inline :card/::card syntax from rich-markdown-reports and replace the ad-hoc embedding section with a "Pair with" section (the convention used by boxel-markdown-format): boxel-flavored-markdown owns the directive grammar, source-code-editing owns the file write. The skill now states only its own concerns (embed live cards, realm file not chat) and points elsewhere for the mechanics. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…rmat Revert the source-code-editing description and index.md catalog changes — that skill is about source code and shouldn't advertise .md. Discovery still works because rich-markdown-reports names and links it directly, so the model pulls it via the cross-reference regardless of its own scope. Reframe the Pair with line to say we reuse the SEARCH/REPLACE block format for the .md, not that a report is source code. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a new skill,
skills/rich-markdown-reports/SKILL.md, that encourages the assistant to author.mdfiles as rich Boxel markdown rather than plain text: embed the live cards and files a report is about via BFM directives (:card/::card/::file), and reference real data instead of restating it.Pure instructions — no bundled tools; the assistant relies on the file-writing tools it already has. It cross-references the
boxel-flavored-markdownskill for the directive grammar rather than duplicating it.Also registers the skill so the pull model can discover it:
index.md— a catalog line under "UI & content".index.mdis the default skill in every AI room; the assistant reads its catalog and pulls a skill'sSKILL.mdon demand, so a skill absent from the catalog is never reached.skills/glossary.md— a one-line entry, per the repo's maintenance contract.Because
skills/**syncs to the skills realm and is copied into the boxel-cli plugin, this serves both the in-app AI assistant (pull model) and the boxel-cli plugin.Verification
boxel.kind: skill(nested underboxel:), so it indexes as a skill file.sync-to-workspacedry-run confirms it pushes/indexes cleanly.index.md), ask for a report and confirm the assistant pullsrich-markdown-reports/SKILL.mdand produces rich BFM with embeds — no manual skill attach required.Linear: https://linear.app/cardstack/issue/CS-12483
🤖 Generated with Claude Code