Add migrate-skill host command to convert legacy Skill cards to SKILL.md by jurgenwerk · Pull Request #5315 · cardstack/boxel

jurgenwerk · 2026-06-23T07:55:04Z

What

Adds a migrate-skill host command (@cardstack/boxel-host/commands/migrate-skill) that scans a realm for legacy Skill cards and writes each one out as a skills/<name>/SKILL.md directory — the markdown-first skill representation the platform now indexes via MarkdownDef.frontmatter / SkillFrontmatterField.

This is Phase B / §8 Phase 2 of the Unified Skills Source spec: "a migrate-skill command converts a user's legacy Skill cards into skills/<name>/SKILL.md directories in their realm."

How

For each skill found in the realm (the type filter matches Skill and its subclasses — SkillPlus, SkillPlusMarkdown), the command maps the card fields onto frontmatter + a markdown body:

cardTitle → top-level name
cardDescription → top-level description
commands (codeRef + requiresApproval) → boxel.commands, the same shape SkillFrontmatterField.commands parses back out, so the host command-definition upload flow reads them identically
instructions → the markdown body
boxel.kind: skill is always added so the file is indexed as a skill

The top-level name / description are shared with Claude Code (which reads the same file byte-for-byte); everything Boxel-specific is namespaced under boxel:.

Example transformation

1. A skill with commands — Skill/data-management.json:

{
  "data": {
    "type": "card",
    "attributes": {
      "cardTitle": "Data Management",
      "cardDescription": "Query and mutate cards in a realm",
      "instructions": "# Data Management\n\nUse `SearchCardsByQuery` to find cards before editing them.",
      "commands": [
        {
          "codeRef": {
            "module": "@cardstack/boxel-host/commands/search-cards",
            "name": "SearchCardsByQueryCommand"
          },
          "requiresApproval": false
        },
        {
          "codeRef": {
            "module": "@cardstack/boxel-host/commands/patch-fields",
            "name": "PatchFieldsCommand"
          },
          "requiresApproval": true
        }
      ]
    },
    "meta": {
      "adoptsFrom": { "module": "https://cardstack.com/base/skill", "name": "Skill" }
    }
  }
}

→ skills/data-management/SKILL.md:

---
name: Data Management
description: Query and mutate cards in a realm
boxel:
  kind: skill
  commands:
    - codeRef:
        module: "@cardstack/boxel-host/commands/search-cards"
        name: SearchCardsByQueryCommand
      requiresApproval: false
    - codeRef:
        module: "@cardstack/boxel-host/commands/patch-fields"
        name: PatchFieldsCommand
      requiresApproval: true
---

# Data Management

Use `SearchCardsByQuery` to find cards before editing them.

2. A skill with no commands — Skill/tone-of-voice.json:

{
  "data": {
    "type": "card",
    "attributes": {
      "cardTitle": "Tone of Voice",
      "cardDescription": "How the assistant should phrase replies",
      "instructions": "Be concise. Prefer plain language over jargon.",
      "commands": []
    },
    "meta": {
      "adoptsFrom": { "module": "https://cardstack.com/base/skill", "name": "Skill" }
    }
  }
}

→ skills/tone-of-voice/SKILL.md (the boxel.commands key is omitted entirely when there are none):

---
name: Tone of Voice
description: How the assistant should phrase replies
boxel:
  kind: skill
---

Be concise. Prefer plain language over jargon.

Behavior notes

Targets that already exist are skipped and reported in skippedSkillIds unless overwrite: true is passed.
Directory slugs are derived from the skill name (Data Management → data-management), de-duplicated within a run, and fall back to the source filename when a skill has no usable name. Skills are processed in a stable id order so the de-dup suffixes (-2, -3) are deterministic — re-running is idempotent (existing targets are recognized and skipped, not duplicated).
Skills with no instructions to transcribe are skipped and reported in emptySkillIds rather than written out as an empty SKILL.md. This guards markdown-backed subclasses (e.g. SkillPlusMarkdown), whose instructions is computed from a linked file that may not resolve in a search result — so nothing is ever silently dropped into an empty file.
The command is non-destructive: it never deletes or repoints the legacy Skill cards. Both representations coexist during the spec's dual-path migration window; removing the push path / Skill class is later-phase cleanup. Existing references (Matrix room enabledSkillCards, linksTo(Skill) fields) keep resolving to the legacy cards and are not rewired here. If a write fails partway, the run aborts but already-written files are skipped on re-run, so re-running resumes safely.

Inputs / outputs

Input (MigrateSkillInput): realm (required), overwrite (optional).
Result (MigrateSkillResult): migratedFiles (URLs written), skippedSkillIds (target already existed), emptySkillIds (no instructions to write).

Testing

Integration test added at packages/host/tests/integration/commands/migrate-skill-test.gts covering: a skill with commands, a skill without commands (no boxel.commands key), and the skip / overwrite behavior. Built on the same realm-seeding pattern as update-room-skills-test.
ember-tsc --noEmit is clean for host; eslint clean on the new host files.

CS-11549

Adds a `migrate-skill` host command that scans a realm for legacy `Skill` cards (and subclasses) and writes each one out as a `skills/<name>/SKILL.md` file with `boxel.kind: skill` frontmatter — the markdown-first skill representation the platform now indexes via `MarkdownDef.frontmatter` / `SkillFrontmatterField`. For each skill the command emits the shared top-level `name`/`description` keys plus a `boxel:` namespace carrying `kind: skill` and the skill's `commands` (codeRef + requiresApproval) in the same shape `SkillFrontmatterField.commands` parses back out. Instructions become the markdown body. Targets that already exist are skipped unless `overwrite` is set, and slug collisions are de-duplicated within a run. CS-11549 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions · 2026-06-23T08:01:54Z

Preview deployments

Host staging preview

Host production preview

Host Test Results

1 files ± 0 1 suites ±0 2h 1m 8s ⏱️ +51s
3 200 tests +18 3 185 ✅ +18 15 💤 ±0 0 ❌ ±0
3 219 runs +18 3 204 ✅ +18 15 💤 ±0 0 ❌ ±0

Results for commit 5b208f6. ± Comparison against earlier commit 8d797a0.

Realm Server Test Results

1 files ±0 1 suites ±0 10m 42s ⏱️ +3s
1 733 tests ±0 1 733 ✅ ±0 0 💤 ±0 0 ❌ ±0
1 826 runs ±0 1 826 ✅ ±0 0 💤 ±0 0 ❌ ±0

Results for commit 5b208f6. ± Comparison against earlier commit 8d797a0.

The `service:realm` stub was registered after `setupBaseRealm` / `setupMockMatrix`, whose beforeEach hooks look up `service:realm` first and instantiate the real singleton — so the later `register` never took effect and `realmOf` ran unstubbed. Resolution then depended on whether the realm happened to be known to the real service, which held only for the first test (cached setup) and failed after teardown. Move the registration ahead of those helpers, matching update-room-skills-test. CS-11549 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Two robustness fixes from a review pass: - Sort skills by id before assigning slugs, so collision suffixes (-2/-3) are stable across runs and the skip-if-exists check stays idempotent rather than minting duplicate files when search order shifts. - Skip and report (new `emptySkillIds`) skills with no instructions instead of writing an empty SKILL.md. This guards markdown-backed subclasses (e.g. SkillPlusMarkdown), whose `instructions` is computed from a linked file that may not resolve in a search result — avoiding silent data loss. CS-11549 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

backspace · 2026-06-23T16:14:33Z

+          let entry: FrontmatterCommand = { codeRef: { module, name } };
+          if (command.requiresApproval) {
+            entry.requiresApproval = true;
+          }


this seems true to me

[Claude Code 🤖]

Fixed in 8d797a0. requiresApproval is now emitted explicitly for every migrated command — command.requiresApproval ?? true — so an explicit false is preserved and a missing value defaults to true, matching command-auto-execute.ts (=== false) and message-builder.ts (?? true). The integration test now seeds both an approval-required and an auto-execute command and asserts the false survives migration.

(Written by Claude on Matic's behalf.)

+              new CommandField({
+                codeRef: { module: COMMAND_MODULE, name: 'DoThing' },
+                requiresApproval: true,
+              }),


+        {
+          codeRef: { module: COMMAND_MODULE, name: 'DoThing' },
+          requiresApproval: true,
+        },
+      ],


chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c120d633bc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-06-24T09:55:40Z

+          if (command.requiresApproval) {
+            entry.requiresApproval = true;
+          }


Preserve false requiresApproval flags

When a legacy skill command explicitly has requiresApproval: false, this migration drops the field because it only writes the flag for truthy values. The migrated markdown then rehydrates the command with requiresApproval unset, and the host's auto-execute predicate only treats commands as approval-free when the value is strictly false (command-auto-execute.ts), so existing no-approval skill commands start requiring manual approval after migration.

Useful? React with 👍 / 👎.

The frontmatter only carried requiresApproval when truthy, so a command with an explicit `requiresApproval: false` lost it. Downstream the host auto-executes a command only when `requiresApproval === false` (command-auto-execute.ts) and otherwise defaults a missing value to `true` (message-builder.ts) — so the dropped `false` silently flipped an auto-executing command back to approval-required. Emit `requiresApproval` explicitly for every command, defaulting a missing source value to `true` to match the downstream default. Test now covers both an approval-required and an auto-execute command and asserts the explicit `false` survives migration. CS-11549 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…l-command-legacy-skill-cards-skillsnameskillmd

jurgenwerk requested a review from Copilot June 23, 2026 09:25

Copilot AI reviewed Jun 23, 2026

jurgenwerk requested review from a team and lukemelia June 23, 2026 11:51

habdelra requested a review from Copilot June 23, 2026 13:04

Copilot started reviewing on behalf of habdelra June 23, 2026 13:04 View session

Copilot AI reviewed Jun 23, 2026

View reviewed changes

lukemelia approved these changes Jun 23, 2026

View reviewed changes

jurgenwerk marked this pull request as ready for review June 24, 2026 09:53

chatgpt-codex-connector Bot reviewed Jun 24, 2026

View reviewed changes

jurgenwerk and others added 2 commits June 24, 2026 12:02

Merge remote-tracking branch 'origin/main' into cs-11549-migrate-skil…

5b208f6

…l-command-legacy-skill-cards-skillsnameskillmd

jurgenwerk merged commit a55e4fb into main Jun 24, 2026
126 of 129 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add migrate-skill host command to convert legacy Skill cards to SKILL.md#5315

Add migrate-skill host command to convert legacy Skill cards to SKILL.md#5315
jurgenwerk merged 5 commits into
mainfrom
cs-11549-migrate-skill-command-legacy-skill-cards-skillsnameskillmd

jurgenwerk commented Jun 23, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 23, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

backspace Jun 23, 2026

Uh oh!

jurgenwerk Jun 24, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Jun 24, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

jurgenwerk commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

How

Example transformation

Behavior notes

Inputs / outputs

Testing

Uh oh!

github-actions Bot commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Preview deployments

Host Test Results

Realm Server Test Results

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

backspace Jun 23, 2026

Choose a reason for hiding this comment

Uh oh!

jurgenwerk Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jurgenwerk commented Jun 23, 2026 •

edited

Loading

github-actions Bot commented Jun 23, 2026 •

edited

Loading