Add filedef-authoring skill for FileDef families and content-only rendering

[lukemelia]

What

Adds .claude/skills/filedef-authoring/SKILL.md, an agent skill covering FileDef authoring and file content rendering:

• Family architecture — the four shared shells in packages/base/file-formats/, FilePreviewStage, static previewComponent as the family hook, and the pin-statics rule for prerender/hydration agreement.
• The wrapped-default decision — the default FileDef templates are the inspector (file bar + metadata) by design; that is not a bug to fix.
• Content-only rendering — the exported MarkdownPreview / ImagePreview / AudioPreview from the file-formats/index barrel, how to pass @model / @format / @displayContainer, kind-dispatch via filePreviewComponentFor, and the format↔@format projection invariant.
• The anti-pattern to avoid — rendering a FileDef field with @displayContainer={{false}} plus :deep() chrome-hiding, and what to do instead.
• Test gotchas — the file-formats/* module manifest in realm-indexing-test.gts and the fileDefFormats count assertions.

The in-app-assistant counterpart (the boxel-file-def skill in the skills realm) is handled separately.

Linear: CS-12591

[lukemelia]

[Claude Code 🤖] Checked this against the published boxel-skills guidance and pushed two additions — ac06208.

• The lever for a wrapped embed you cannot pass args to. boxel-ui-guidelines/references/delegated-render-control.md makes the point that a framework-driven <@fields.file @format='embedded' /> takes no component args at all, so @displayContainer is not available there — and the cross-boundary lever is an inherited custom property (markdown reads --md-preview-background, --md-preview-foreground, --md-preview-padding; all three verified in markdown-preview.gts). Without that, an author who wants to tune a wrapped embed is sent straight back to the :deep() this skill tells them not to use.
• The barrel is the list. Which families have a content-only renderer now points at file-formats/index.ts instead of naming three, so the skill cannot go stale behind it — which it otherwise would the moment the video renderer lands.

[Copilot]

🟡 Changes recommended

Several API, dependency, layering, and source-reference details need correction.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds a Claude skill documenting FileDef families, content-only rendering, anti-patterns, and testing guidance.

Changes:

• Documents shared shells and preview dispatch.
• Explains Markdown, Image, and Audio content-only components.
• Covers rendering pitfalls and test-manifest considerations.

File summaries

File	Description
.claude/skills/filedef-authoring/SKILL.md	Adds FileDef authoring and rendering guidance.

Review details

Suppressed comments (6)

.claude/skills/filedef-authoring/SKILL.md:61

• [Claude Code 🤖] The cited field guide is itself the exact pattern this section forbids: it renders <@fields.file ... @displayContainer={{false}} /> and hides .markdown-embedded__title / unclamps .markdown-embedded__content with :deep() (packages/experiments-realm/filedef-fixtures/file-embedding-field-guide.gts:47,126-145). Linking it as a worked example sends authors to the wrong implementation; remove this reference or replace the fixture with a direct MarkdownPreview example.

This reaches into shell internals with `:deep()` to hide chrome and un-clamp content. The targeted classes are renderer-internal, not a stable contract, so the CSS breaks silently when the renderer's markup changes — and it duplicates what the content-only components already do. Render `<MarkdownPreview …>` (or `ImagePreview` / `AudioPreview`) directly instead. For worked examples, see `experiments-realm/filedef-fixtures/file-embedding-field-guide.gts` and boxel-home's `LegalDoc`.

.claude/skills/filedef-authoring/SKILL.md:32

• [Claude Code 🤖] These names are not module-private content-only renderers in file-formats/: they are private classes in packages/base/*-file-def.gts implementing the shell's FilePreviewSignature. Calling them “the rest” of the barrel exports suggests they can be used like MarkdownPreview, but they are not exported by the barrel and do not accept a bare FileDef instance. Please describe them as family renderers or remove this list.

Which families have a content-only renderer is what the barrel exports — read `file-formats/index.ts` rather than a list here. The rest (`TextPreview`, `CsvPreview`, `JsonPreview`, `CodePreview`, `ArchivePreview`) are module-private; export one from the barrel as call sites need it.

.claude/skills/filedef-authoring/SKILL.md:14

• [Claude Code 🤖] FilePreviewStage does not own a current-render cache or provenance overlay: its template renders thumbnails, previews/fallbacks, state panes, and stale/malformed indicators, while provenance is explicitly kept in FileIsolatedShell. Calling those concerns stage-owned can lead authors to put provenance or caching into the wrong layer.

- **`FilePreviewStage`** is the slot the shells project into. It owns the concerns every family shares — the current-render cache, loading / failure / staleness panes, provenance, and the generic fallback pane for a family with no renderer.
- **`static previewComponent`** is the family hook. A `FileDef` subclass sets `static previewComponent = XPreview`; `FilePreviewStage` mounts it. `filePreviewComponentFor(instance)` resolves the renderer a file's class declares (read off the instance's constructor, since a `linksTo(FileDef)` is routinely a subclass instance).

.claude/skills/filedef-authoring/SKILL.md:65

• [Claude Code 🤖] The field wrapper does accept the generic @format and @displayContainer arguments (BoxComponentSignature), but it does not forward arbitrary arguments to the FileDef format component. Saying the invocation takes no component args is inaccurate and conflicts with the example immediately before it; describe the forwarding boundary instead.

To tune a wrapped embed you cannot pass args to at all — a framework-driven `<@fields.file @format='embedded' />`, which takes no component args — the cross-boundary lever is an inherited custom property, not a selector: markdown reads `--md-preview-background`, `--md-preview-foreground`, and `--md-preview-padding` from any ancestor. The boxel-skills reference `boxel-ui-guidelines/references/delegated-render-control.md` covers the general case (a `class` on the field, the theme cascade, what a child must never decorate).

.claude/skills/filedef-authoring/SKILL.md:17

• [Claude Code 🤖] This makes a custom renderer mandatory for every new family, but FileDef.previewComponent is optional and VideoDef is a current family with no preview component; it relies on the generic fallback. Qualify this as the recipe for families that provide a custom preview so authors do not add a renderer merely to follow the skill.

So a new family = add `@field`s + a `previewComponent`. It should not touch the shells.

.claude/skills/filedef-authoring/SKILL.md:30

• [Claude Code 🤖] The host example is not valid for host-side runtime modules: this repository loads base-realm value modules through loader.import(...) and uses @cardstack/base/... statically only for types. A static value import here can trigger the host build's missing-module failure; document the loader form for host code instead.

- Host / base TS: `import { MarkdownPreview } from '@cardstack/base/file-formats/index';`

• Files reviewed: 1/1 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.