@rune-kit/rune 2.22.2 → 2.23.0

package/README.md

@@ -83,7 +83,11 @@ _Methodology: Claude Code CLI headless mode (`claude -p --output-format json`),
 
 ---
 
-## What's New (v2.22.2 — Convergence, Dogfooded)
+## What's New (v2.23.0 — Native Skills)
+
+> **v2.23.0 (2026-07-04):** Seven platform adapters move to the **Agent Skills open standard** (dir-per-skill `SKILL.md`, discovered and lazy-loaded by each platform's native loader). The headline fix: **Codex** dropped `.codex/skills/` from its scan list, so compiled skills were only findable via the AGENTS.md pointer — agents kept "re-finding" the path mid-session. Codex now emits to **`.agents/skills/`** (scanned CWD → repo root). Same treatment across the fleet: **cursor** `.cursor/rules/*.mdc` → `.cursor/skills/` (Cursor 2.4+ Skills, on-demand instead of always-on), **windsurf** → `.windsurf/skills/` (Cascade Skills), **copilot** → `.github/skills/`, **qoder** → `.qoder/skills/`, and **gemini/qwen** drop their all-skills-always-on context bombs (GEMINI.md bundle, QWEN.md `@import` wall) for native `.gemini/skills/` / `.qwen/skills/` + slim pointer files — a big context-window win on those platforms. Runtime hooks intentionally stay on `.cursor/rules` / `.windsurf/rules` (always-on is correct for hook context). Also fixes a YAML double-escaping bug that corrupted compiled frontmatter for skills with quoted descriptions on 6 platforms, and a duplicate `scripts/` copy in dir-per-skill builds. If you previously built for Codex/Cursor/Windsurf/Copilot/Gemini/Qwen/Qoder: re-run `npx @rune-kit/rune build` and delete the old output dirs. CI 1571/1571.
+
+### Previous (v2.22.2 — Convergence, Dogfooded)
 
 > **v2.22.2 (2026-07-04):** Patch: `rune setup` now installs tier skills into the Claude Code PLUGIN CACHE (newest version dir) instead of the executing package's own root — npx runs were copying Pro skills into npx's ephemeral cache (invisible to the plugin runtime, 'Unknown skill: rune:autopilot' returned), and source-checkout runs polluted the git tree. **v2.22.1:** tier-hook loader accepts PreCompact + SessionStart lifecycle events — required by Pro hooks v1.2.0 (context-reset). **v2.22.0:** The v2.21.0 gates went through a live-fire dogfood: fresh executor agents (zero author context) ran `converge` and `verification` Level 3.5 against a fixture with a dead Submit button, a handler-less Export button, a navigation-anchor decoy, and a declared placeholder. **Both gates caught the dead button with file:line evidence and zero false positives** — and the 16 ambiguities the executors reported became spec fixes: converge v0.2.0 adds a `deferred-debt` class (declared design debt can no longer force a false escalation), a `Plan Claims vs Reality` section (tasks marked `[x]` whose code doesn't exist — surfaced first-class), and derived story verdicts; verification v0.7.0 gets FAIL-dominates precedence, per-route reverse checks, and server/static entry-point exemptions. The dogfood fixture itself shipped as the seed of **`npm run eval`** — a behavioral eval harness that runs a fresh headless agent against fixture repos and asserts outcomes, because structural validation can't prove a skill makes an agent behave. Pro `autopilot` v1.6.0 now explicitly runs Phase 6.5 CONVERGE in autonomous mode.
 

package/compiler/__tests__/adapters.test.js

@@ -29,7 +29,7 @@ test('listPlatforms returns all 13 platform adapters', () => {
 test('getAdapter returns adapter by name', () => {
   const cursor = getAdapter('cursor');
   assert.strictEqual(cursor.name, 'cursor');
-  assert.strictEqual(cursor.fileExtension, '.mdc');
+  assert.strictEqual(cursor.fileExtension, '.md');
 });
 
 test('getAdapter throws for unknown adapter', () => {
@@ -112,18 +112,45 @@ for (const adapterName of ADAPTER_NAMES) {
   });
 }
 
+// --- Frontmatter escaping (regression: descriptions containing quoted phrases) ---
+
+test('generateHeader escapes quoted descriptions exactly once (valid YAML)', () => {
+  // Parser hands adapters CLEAN text (interior \" already unescaped) — the
+  // adapter re-escapes exactly once. Double-escaping produced `\\"` which
+  // prematurely terminates the YAML scalar.
+  const skill = { name: 'docs', layer: 'L2', group: 'workflow', description: 'The "docs are never outdated" skill' };
+  for (const name of ['cursor', 'windsurf', 'copilot', 'codex', 'antigravity', 'opencode', 'gemini', 'qoder', 'qwen']) {
+    const header = getAdapter(name).generateHeader(skill);
+    assert.ok(header.includes('\\"docs are never outdated\\"'), `${name} should escape quotes once`);
+    assert.ok(!header.includes('\\\\"'), `${name} must not double-escape quotes`);
+  }
+});
+
 // --- Cursor-specific ---
 
-test('cursor adapter generates .mdc frontmatter with alwaysApply', () => {
+test('cursor adapter emits Agent Skills (dir-per-skill SKILL.md)', () => {
   const cursor = getAdapter('cursor');
-  const l0Skill = { name: 'router', layer: 'L0', group: 'meta', description: 'Routes tasks' };
-  const l2Skill = { name: 'fix', layer: 'L2', group: 'workflow', description: 'Fix code' };
+  assert.strictEqual(cursor.outputDir, '.cursor/skills');
+  assert.strictEqual(cursor.useSkillDirectories, true);
+  assert.strictEqual(cursor.skillFileName, 'SKILL.md');
 
-  const l0Header = cursor.generateHeader(l0Skill);
-  assert.ok(l0Header.includes('alwaysApply: true'));
+  const header = cursor.generateHeader({ name: 'fix', layer: 'L2', group: 'workflow', description: 'Fix code' });
+  assert.ok(header.includes('name: rune-fix'));
+  assert.ok(header.includes('description: "Fix code"'));
+  assert.ok(!header.includes('alwaysApply'), 'skills format has no alwaysApply');
+});
 
-  const l2Header = cursor.generateHeader(l2Skill);
-  assert.ok(l2Header.includes('alwaysApply: false'));
+// --- Windsurf-specific ---
+
+test('windsurf adapter emits Cascade Skills (dir-per-skill SKILL.md)', () => {
+  const windsurf = getAdapter('windsurf');
+  assert.strictEqual(windsurf.outputDir, '.windsurf/skills');
+  assert.strictEqual(windsurf.useSkillDirectories, true);
+  assert.strictEqual(windsurf.skillFileName, 'SKILL.md');
+
+  const header = windsurf.generateHeader({ name: 'fix', layer: 'L2', group: 'workflow', description: 'Fix code' });
+  assert.ok(header.includes('name: rune-fix'));
+  assert.ok(header.includes('description: "Fix code"'));
 });
 
 // --- Codex-specific ---
@@ -136,26 +163,35 @@ test('codex adapter uses skill directories', () => {
 
 // --- New v2.18 adapters: shape + generateExtraFiles contract ---
 
-test('qoder adapter targets .qoder/rules and emits AGENTS.md', async () => {
+test('qoder adapter targets .qoder/skills (dir-per-skill) and emits AGENTS.md', async () => {
   const qoder = getAdapter('qoder');
-  assert.strictEqual(qoder.outputDir, '.qoder/rules');
-  assert.strictEqual(qoder.useSkillDirectories, false);
+  assert.strictEqual(qoder.outputDir, '.qoder/skills');
+  assert.strictEqual(qoder.useSkillDirectories, true);
+  assert.strictEqual(qoder.skillFileName, 'SKILL.md');
   assert.strictEqual(typeof qoder.generateExtraFiles, 'function');
   const extras = await qoder.generateExtraFiles({ stats: { skillCount: 5, packCount: 1, files: [] } });
-  assert.ok(extras.some((e) => e.path === 'AGENTS.md' && e.content.includes('Rune')));
+  assert.ok(extras.some((e) => e.path === 'AGENTS.md' && e.content.includes('.qoder/skills')));
 });
 
-test('copilot adapter targets .github/instructions with .instructions.md ext', async () => {
+test('copilot adapter targets .github/skills with SKILL.md format', async () => {
   const copilot = getAdapter('copilot');
-  assert.strictEqual(copilot.outputDir, '.github/instructions');
-  assert.strictEqual(copilot.fileExtension, '.instructions.md');
-  const header = copilot.generateHeader({ name: 'cook', layer: 'L1', group: 'orchestrator', description: 'Test' });
-  // Per docs.github.com Copilot CLI custom-instructions spec, only `applyTo` is a
-  // documented frontmatter field. Description and tier-hint must live in the body.
-  assert.ok(header.includes('applyTo: "**"'));
-  assert.ok(!/^description:/m.test(header.split('---')[1] || ''), 'description must NOT appear in frontmatter');
+  assert.strictEqual(copilot.outputDir, '.github/skills');
+  assert.strictEqual(copilot.useSkillDirectories, true);
+  assert.strictEqual(copilot.skillFileName, 'SKILL.md');
+  const header = copilot.generateHeader({
+    name: 'cook',
+    layer: 'L1',
+    group: 'orchestrator',
+    description: 'Test',
+    model: 'opus',
+  });
+  // Agent Skills spec: name + description frontmatter; tier hint stays a body comment.
+  assert.ok(header.includes('name: rune-cook'));
+  assert.ok(header.includes('description: "Test"'));
+  assert.ok(header.includes('<!-- tier-hint: tier:heavy -->'));
+  assert.ok(!header.includes('applyTo'), 'skills format has no applyTo');
   const extras = await copilot.generateExtraFiles({ stats: { skillCount: 5, packCount: 1, files: [] } });
-  assert.ok(extras.some((e) => e.path === '.github/copilot-instructions.md'));
+  assert.ok(extras.some((e) => e.path === '.github/copilot-instructions.md' && e.content.includes('.github/skills')));
   assert.ok(extras.some((e) => e.path === 'AGENTS.md'));
 });
 
@@ -201,21 +237,30 @@ test('aider adapter emits .aider.conf.yml with read array', async () => {
   assert.ok(!conf.content.includes('aider/rules/index.md'));
 });
 
-test('qwen adapter emits QWEN.md with @import lines', async () => {
+test('qwen adapter targets .qwen/skills and emits slim QWEN.md pointer', async () => {
   const qwen = getAdapter('qwen');
-  assert.strictEqual(qwen.outputDir, 'qwen/skills');
+  assert.strictEqual(qwen.outputDir, '.qwen/skills');
+  assert.strictEqual(qwen.useSkillDirectories, true);
+  assert.strictEqual(qwen.skillFileName, 'SKILL.md');
   const extras = await qwen.generateExtraFiles({
-    stats: { skillCount: 2, packCount: 0, files: ['rune-cook.md', 'rune-fix.md'] },
+    stats: { skillCount: 2, packCount: 0, files: ['rune-cook/SKILL.md', 'rune-fix/SKILL.md'] },
   });
   const qwenMd = extras.find((e) => e.path === 'QWEN.md');
   assert.ok(qwenMd);
-  assert.ok(qwenMd.content.includes('@qwen/skills/rune-cook.md'));
-  assert.ok(qwenMd.content.includes('@qwen/skills/rune-fix.md'));
+  assert.ok(qwenMd.content.includes('.qwen/skills/rune-<name>/SKILL.md'));
+  assert.ok(!qwenMd.content.includes('@qwen/skills/'), 'no @import lines — skills are lazy-loaded natively');
 });
 
-test('gemini adapter declares generateExtraFiles for bundled GEMINI.md', () => {
+test('gemini adapter targets .gemini/skills and emits slim GEMINI.md pointer', async () => {
   const gemini = getAdapter('gemini');
-  assert.strictEqual(gemini.outputDir, 'gemini/skills');
-  assert.strictEqual(typeof gemini.generateExtraFiles, 'function');
-  // Full bundle test happens in pipeline test (needs filesystem) — contract checked here.
+  assert.strictEqual(gemini.outputDir, '.gemini/skills');
+  assert.strictEqual(gemini.useSkillDirectories, true);
+  assert.strictEqual(gemini.skillFileName, 'SKILL.md');
+  const extras = await gemini.generateExtraFiles({
+    stats: { skillCount: 2, packCount: 0, files: ['rune-cook/SKILL.md', 'rune-fix/SKILL.md'] },
+  });
+  const geminiMd = extras.find((e) => e.path === 'GEMINI.md');
+  assert.ok(geminiMd);
+  assert.ok(geminiMd.content.includes('.gemini/skills/rune-<name>/SKILL.md'));
+  assert.ok(!geminiMd.content.includes('## rune-cook'), 'no bundled H2 sections — skills are lazy-loaded natively');
 });

package/compiler/__tests__/pack-split.test.js

@@ -244,7 +244,10 @@ describe('buildAll split pack auto-discovery', () => {
       assert.strictEqual(stats.packCount, 1, 'should build 1 pack');
 
       // Read the compiled pack output
-      const packOutput = await readFile(path.join(outputRoot, adapter.outputDir, 'rune-ext-test-pack.mdc'), 'utf-8');
+      const packOutput = await readFile(
+        path.join(outputRoot, adapter.outputDir, 'rune-ext-test-pack', 'SKILL.md'),
+        'utf-8',
+      );
 
       // Should contain the pack index body
       assert.ok(packOutput.includes('Pack index body'), 'missing pack index body');
@@ -270,7 +273,7 @@ describe('buildAll split pack auto-discovery', () => {
     await buildAll({ runeRoot, outputRoot: tmp, adapter });
 
     try {
-      const packOutput = await readFile(path.join(tmp, adapter.outputDir, 'rune-ext-ai-ml.mdc'), 'utf-8');
+      const packOutput = await readFile(path.join(tmp, adapter.outputDir, 'rune-ext-ai-ml', 'SKILL.md'), 'utf-8');
 
       // Should be significantly longer than just the index body (~99 lines without skills)
       const lineCount = packOutput.split('\n').length;

package/compiler/__tests__/pipeline.test.js

@@ -58,12 +58,12 @@ describe('full pipeline: cook skill', () => {
 });
 
 describe('full pipeline: fix skill', () => {
-  test('cursor: cross-refs transformed to .mdc', () => {
+  test('cursor: cross-refs transformed to skill references', () => {
     const adapter = getAdapter('cursor');
     const result = transformSkill(fixParsed, adapter);
 
     // Fix references cook, debug, test, etc. — at least some should be transformed
-    assert.ok(result.body.includes('.mdc'), 'cursor output should contain .mdc references');
+    assert.ok(result.body.includes('the rune-'), 'cursor output should contain skill references');
   });
 
   test('generic: cross-refs transformed to descriptive text', () => {
@@ -82,15 +82,15 @@ describe('full pipeline: fix skill', () => {
 // --- Output assembly (header + body + footer) ---
 
 describe('output assembly', () => {
-  test('cursor output assembles into valid .mdc file', () => {
+  test('cursor output assembles into valid SKILL.md file', () => {
     const adapter = getAdapter('cursor');
     const result = transformSkill(cookParsed, adapter);
     const assembled = result.header + result.body + result.footer;
 
     // Should start with YAML frontmatter
-    assert.ok(assembled.startsWith('---\n'), 'cursor .mdc should start with YAML frontmatter');
-    assert.ok(assembled.includes('description:'), 'cursor .mdc should have description');
-    assert.ok(assembled.includes('alwaysApply:'), 'cursor .mdc should have alwaysApply');
+    assert.ok(assembled.startsWith('---\n'), 'cursor SKILL.md should start with YAML frontmatter');
+    assert.ok(assembled.includes('name: rune-'), 'cursor SKILL.md should have name');
+    assert.ok(assembled.includes('description:'), 'cursor SKILL.md should have description');
   });
 
   test('codex output has YAML frontmatter with name', () => {

package/compiler/__tests__/scripts-bundling.test.js

@@ -54,7 +54,7 @@ describe('resolveScriptsPath', () => {
 
 describe('adapter scriptsDir', () => {
   test('flat-file adapters return sibling dir pattern', () => {
-    for (const name of ['cursor', 'windsurf', 'antigravity', 'generic', 'openclaw']) {
+    for (const name of ['generic', 'openclaw']) {
       const adapter = getAdapter(name);
       assert.ok(adapter.scriptsDir, `${name} should have scriptsDir`);
       assert.strictEqual(adapter.scriptsDir('slides'), 'rune-slides-scripts', `${name} scriptsDir mismatch`);
@@ -62,7 +62,17 @@ describe('adapter scriptsDir', () => {
   });
 
   test('directory-per-skill adapters return nested dir pattern', () => {
-    for (const name of ['codex', 'opencode']) {
+    for (const name of [
+      'codex',
+      'opencode',
+      'cursor',
+      'windsurf',
+      'copilot',
+      'qoder',
+      'gemini',
+      'qwen',
+      'antigravity',
+    ]) {
       const adapter = getAdapter(name);
       assert.ok(adapter.scriptsDir, `${name} should have scriptsDir`);
       assert.strictEqual(adapter.scriptsDir('slides'), 'rune-slides/scripts', `${name} scriptsDir mismatch`);
@@ -143,7 +153,7 @@ describe('buildAll with scripts', () => {
     return tmp;
   }
 
-  test('cursor: scripts copied to sibling dir, placeholder resolved', async () => {
+  test('cursor: scripts inside skill directory, placeholder resolved', async () => {
     const tmp = await createTempSkillTree();
     try {
       const outputRoot = path.join(tmp, 'out');
@@ -153,19 +163,19 @@ describe('buildAll with scripts', () => {
       // Scripts copied
       assert.ok(stats.scriptsCopied >= 2, `expected 2+ scripts copied, got ${stats.scriptsCopied}`);
 
-      // Scripts dir exists with files
-      const scriptsOut = path.join(outputRoot, adapter.outputDir, 'rune-test-slide-scripts');
+      // Scripts inside skill dir: .cursor/skills/rune-test-slide/scripts/
+      const scriptsOut = path.join(outputRoot, adapter.outputDir, 'rune-test-slide', 'scripts');
       assert.ok(existsSync(path.join(scriptsOut, 'build-deck.js')), 'build-deck.js missing in output');
       assert.ok(existsSync(path.join(scriptsOut, 'helper.py')), 'helper.py missing in output');
 
-      // Placeholder resolved in .mdc output
-      const mdc = await readFile(path.join(outputRoot, adapter.outputDir, 'rune-test-slide.mdc'), 'utf-8');
-      assert.ok(!mdc.includes('{scripts_dir}'), 'placeholder should be resolved');
-      assert.ok(mdc.includes('.cursor/rules/rune-test-slide-scripts/build-deck.js'), 'resolved path missing');
+      // Placeholder resolved in SKILL.md output
+      const md = await readFile(path.join(outputRoot, adapter.outputDir, 'rune-test-slide', 'SKILL.md'), 'utf-8');
+      assert.ok(!md.includes('{scripts_dir}'), 'placeholder should be resolved');
+      assert.ok(md.includes('.cursor/skills/rune-test-slide/scripts/build-deck.js'), 'resolved path missing');
 
       // Plain skill: no scripts dir created
       assert.ok(
-        !existsSync(path.join(outputRoot, adapter.outputDir, 'rune-test-plain-scripts')),
+        !existsSync(path.join(outputRoot, adapter.outputDir, 'rune-test-plain', 'scripts')),
         'plain skill should not have scripts dir',
       );
     } finally {
@@ -182,7 +192,7 @@ describe('buildAll with scripts', () => {
 
       assert.ok(stats.scriptsCopied >= 2);
 
-      // Scripts inside skill dir: .codex/skills/rune-test-slide/scripts/
+      // Scripts inside skill dir: .agents/skills/rune-test-slide/scripts/
       const scriptsOut = path.join(outputRoot, adapter.outputDir, 'rune-test-slide', 'scripts');
       assert.ok(existsSync(path.join(scriptsOut, 'build-deck.js')), 'build-deck.js missing');
       assert.ok(existsSync(path.join(scriptsOut, 'helper.py')), 'helper.py missing');
@@ -190,7 +200,7 @@ describe('buildAll with scripts', () => {
       // Placeholder resolved
       const md = await readFile(path.join(outputRoot, adapter.outputDir, 'rune-test-slide', 'SKILL.md'), 'utf-8');
       assert.ok(!md.includes('{scripts_dir}'), 'placeholder should be resolved');
-      assert.ok(md.includes('.codex/skills/rune-test-slide/scripts/build-deck.js'), 'resolved path missing');
+      assert.ok(md.includes('.agents/skills/rune-test-slide/scripts/build-deck.js'), 'resolved path missing');
     } finally {
       await rm(tmp, { recursive: true, force: true });
     }
@@ -251,7 +261,7 @@ describe('buildAll with scripts', () => {
 
       const original = await readFile(path.join(tmp, 'skills', 'test-slide', 'scripts', 'build-deck.js'), 'utf-8');
       const copied = await readFile(
-        path.join(outputRoot, adapter.outputDir, 'rune-test-slide-scripts', 'build-deck.js'),
+        path.join(outputRoot, adapter.outputDir, 'rune-test-slide', 'scripts', 'build-deck.js'),
         'utf-8',
       );
       assert.strictEqual(copied, original, 'script content should be identical');
@@ -263,19 +273,19 @@ describe('buildAll with scripts', () => {
   test('multiple adapters resolve different paths', async () => {
     const tmp = await createTempSkillTree();
     try {
-      // Cursor (flat)
+      // Cursor (directory)
       const cursorOut = path.join(tmp, 'out-cursor');
       const cursorAdapter = getAdapter('cursor');
       await buildAll({ runeRoot: tmp, outputRoot: cursorOut, adapter: cursorAdapter });
-      const cursorMdc = await readFile(path.join(cursorOut, '.cursor/rules/rune-test-slide.mdc'), 'utf-8');
-      assert.ok(cursorMdc.includes('.cursor/rules/rune-test-slide-scripts/'), 'cursor path');
+      const cursorMd = await readFile(path.join(cursorOut, '.cursor/skills/rune-test-slide/SKILL.md'), 'utf-8');
+      assert.ok(cursorMd.includes('.cursor/skills/rune-test-slide/scripts/'), 'cursor path');
 
-      // Codex (directory)
+      // Codex (directory, shared .agents/skills standard)
       const codexOut = path.join(tmp, 'out-codex');
       const codexAdapter = getAdapter('codex');
       await buildAll({ runeRoot: tmp, outputRoot: codexOut, adapter: codexAdapter });
-      const codexMd = await readFile(path.join(codexOut, '.codex/skills/rune-test-slide/SKILL.md'), 'utf-8');
-      assert.ok(codexMd.includes('.codex/skills/rune-test-slide/scripts/'), 'codex path');
+      const codexMd = await readFile(path.join(codexOut, '.agents/skills/rune-test-slide/SKILL.md'), 'utf-8');
+      assert.ok(codexMd.includes('.agents/skills/rune-test-slide/scripts/'), 'codex path');
     } finally {
       await rm(tmp, { recursive: true, force: true });
     }

package/compiler/__tests__/transformer.test.js

@@ -27,10 +27,10 @@ describe('transformSkill', () => {
     assert.strictEqual(result.footer, '');
   });
 
-  test('Cursor adapter transforms cross-refs to .mdc format', () => {
+  test('Cursor adapter transforms cross-refs to skill references', () => {
     const cursor = getAdapter('cursor');
     const result = transformSkill(mockSkill, cursor);
-    assert.ok(result.body.includes('@rune-cook.mdc'));
+    assert.ok(result.body.includes('the rune-cook skill'));
     assert.ok(!result.body.includes('rune:cook'));
   });
 
@@ -44,11 +44,11 @@ describe('transformSkill', () => {
     assert.ok(result.footer.length > 0, 'footer should not be empty for non-Claude');
   });
 
-  test('Cursor header contains frontmatter with description', () => {
+  test('Cursor header contains SKILL.md frontmatter with name and description', () => {
     const cursor = getAdapter('cursor');
     const result = transformSkill(mockSkill, cursor);
+    assert.ok(result.header.includes('name: rune-'));
     assert.ok(result.header.includes('description:'));
-    assert.ok(result.header.includes('alwaysApply:'));
   });
 
   test('Generic adapter transforms refs to descriptive text', () => {

package/compiler/adapters/antigravity.js

@@ -74,11 +74,7 @@ export default {
   },
 
   scriptsDir(skillName) {
-    return `rune-${skillName}-scripts`;
-  },
-
-  referencesDir(skillName) {
-    return `rune-${skillName}-references`;
+    return `rune-${skillName}/scripts`;
   },
 
   postProcess(content) {

package/compiler/adapters/codex.js

@@ -1,13 +1,17 @@
 /**
  * OpenAI Codex Adapter
  *
- * Emits SKILL.md files into .codex/skills/{name}/ directories.
+ * Emits SKILL.md files into .agents/skills/{name}/ directories.
  * Codex uses the same SKILL.md frontmatter format (name, description)
  * with markdown body — very close to Rune's native format.
  *
  * Codex project context: AGENTS.md (equivalent to CLAUDE.md)
- * Codex skills dir: .codex/skills/
- * Codex skill format: .codex/skills/{name}/SKILL.md
+ * Codex skills dir: .agents/skills/ (scanned from CWD up to repo root)
+ * Codex skill format: .agents/skills/{name}/SKILL.md
+ *
+ * NOTE: Codex dropped .codex/skills/ from its scan list — .codex/ is config
+ * only (config.toml). Repo skills MUST live in .agents/skills/ to be
+ * auto-discovered. @see https://developers.openai.com/codex/skills
  *
  * MODEL TIER MAPPING (v2.15+):
  * Skill frontmatter `model: opus|sonnet|haiku` (Anthropic naming) is
@@ -37,12 +41,12 @@ const TOOL_MAP = {
 
 export default {
   name: 'codex',
-  outputDir: '.codex/skills',
+  outputDir: '.agents/skills',
   fileExtension: '.md',
   skillPrefix: 'rune-',
   skillSuffix: '',
 
-  // Codex uses directory-per-skill: .codex/skills/{name}/SKILL.md
+  // Codex uses directory-per-skill: .agents/skills/{name}/SKILL.md
   useSkillDirectories: true,
   skillFileName: 'SKILL.md',
 
@@ -105,7 +109,7 @@ export default {
       '',
       '## Skills Directory',
       '',
-      'Skills are located in: .codex/skills/',
+      'Skills are located in: .agents/skills/ (auto-discovered by Codex)',
       '',
       '---',
       '> Rune Skill Mesh — https://github.com/rune-kit/rune',

package/compiler/adapters/copilot.js

@@ -1,19 +1,17 @@
 /**
- * GitHub Copilot CLI Adapter
+ * GitHub Copilot Adapter
  *
- * Emits per-skill instruction files into .github/instructions/ — the documented
- * convention for GitHub Copilot custom instructions (read by both the CLI and
- * the GitHub Copilot IDE plugin family).
+ * Emits SKILL.md files into .github/skills/{name}/ directories — GitHub
+ * Copilot's native Agent Skills format (supported since Dec 2025 across
+ * Copilot CLI, VS Code agent mode, and github.com). Skills are loaded
+ * on-demand based on the description, keeping context lean.
  *
- * Copilot instructions dir: .github/instructions/
- * Copilot instruction file: .github/instructions/rune-{name}.instructions.md
+ * Copilot skills dir: .github/skills/ (also reads .claude/skills and .agents/skills)
+ * Copilot skill format: .github/skills/{name}/SKILL.md
  * Copilot project context: AGENTS.md (Copilot Spaces / Coding Agent convention)
  *
- * Each .instructions.md uses YAML frontmatter with `applyTo` for path scoping.
- * Default applyTo: "**" means "apply to all files."
- *
- * @see https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions
- * @see https://docs.github.com/en/copilot/concepts/response-customization
+ * @see https://docs.github.com/en/copilot/concepts/agents/about-agent-skills
+ * @see https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills
  *
  * MODEL TIER MAPPING (v2.18+):
  * Copilot multi-model support exposes Anthropic/OpenAI/Google providers. Tier
@@ -37,23 +35,24 @@ const TOOL_MAP = {
   Grep: 'search file contents',
   Bash: 'run a shell command',
   TodoWrite: 'track task progress',
-  Skill: 'follow the referenced instructions',
+  Skill: 'invoke the named skill',
   Agent: 'execute the workflow',
 };
 
 export default {
   name: 'copilot',
-  outputDir: '.github/instructions',
-  fileExtension: '.instructions.md',
+  outputDir: '.github/skills',
+  fileExtension: '.md',
   skillPrefix: 'rune-',
   skillSuffix: '',
 
-  // Copilot instructions are flat per-skill files, not directories.
-  useSkillDirectories: false,
+  // Copilot uses directory-per-skill: .github/skills/{name}/SKILL.md
+  useSkillDirectories: true,
+  skillFileName: 'SKILL.md',
 
   transformReference(skillName, raw) {
     const isBackticked = raw.startsWith('`') && raw.endsWith('`');
-    const ref = `the rune-${skillName} instructions`;
+    const ref = `the rune-${skillName} skill`;
     return isBackticked ? `\`${ref}\`` : ref;
   },
 
@@ -62,15 +61,13 @@ export default {
   },
 
   generateHeader(skill) {
-    // Per docs.github.com Copilot CLI custom-instructions spec, the only
-    // documented frontmatter key for `.instructions.md` is `applyTo`. Other
-    // metadata (description, tier hint) belongs in the markdown body so it
-    // survives parsing across CLI/IDE/extensions consistently.
-    const desc = (skill.description || '').replace(/\n/g, ' ');
+    // Agent Skills spec: name + description frontmatter, markdown body.
+    // Tier hint stays a body comment — Copilot has no model frontmatter key.
+    const desc = (skill.description || '').replace(/"/g, '\\"');
     const tierHint = skill.model ? MODEL_MAP[skill.model] || skill.model : null;
-    const lines = ['---', 'applyTo: "**"', '---', '', `# rune-${skill.name}`, '', `> ${desc}`];
-    if (tierHint) lines.push('', `<!-- tier-hint: ${tierHint} -->`);
-    lines.push('', '');
+    const lines = ['---', `name: rune-${skill.name}`, `description: "${desc}"`, '---', ''];
+    if (tierHint) lines.push(`<!-- tier-hint: ${tierHint} -->`, '');
+    lines.push('');
     return lines.join('\n');
   },
 
@@ -83,7 +80,7 @@ export default {
   },
 
   scriptsDir(skillName) {
-    return `rune-${skillName}-scripts`;
+    return `rune-${skillName}/scripts`;
   },
 
   postProcess(content) {
@@ -96,9 +93,9 @@ export default {
     const copilotIndex = [
       '# Rune — Copilot Custom Instructions',
       '',
-      `Per-skill instructions live under \`.github/instructions/rune-<name>.instructions.md\` (${stats.skillCount} skills + ${stats.packCount} packs). Copilot loads them based on each file's \`applyTo\` glob.`,
+      `Per-skill Agent Skills live under \`.github/skills/rune-<name>/SKILL.md\` (${stats.skillCount} skills + ${stats.packCount} packs). Copilot discovers and loads them on demand based on each skill's description.`,
       '',
-      'When a user request matches a skill\'s domain (e.g. "fix the failing test", "review this PR"), prefer following the corresponding rune-<name>.instructions.md over freestyling.',
+      'When a user request matches a skill\'s domain (e.g. "fix the failing test", "review this PR"), prefer invoking the corresponding rune-<name> skill over freestyling.',
       '',
       '---',
       '> Rune Skill Mesh — https://github.com/rune-kit/rune',
@@ -111,7 +108,7 @@ export default {
       'Rune is an interconnected skill ecosystem for AI coding assistants.',
       `${stats.skillCount} core skills + ${stats.packCount} extension packs.`,
       '',
-      'Per-skill custom instructions: `.github/instructions/rune-<name>.instructions.md`',
+      'Per-skill Agent Skills: `.github/skills/rune-<name>/SKILL.md`',
       '',
       '---',
       '> Rune Skill Mesh — https://github.com/rune-kit/rune',

package/compiler/adapters/cursor.js

@@ -1,8 +1,18 @@
 /**
  * Cursor Adapter
  *
- * Emits .mdc rule files for .cursor/rules/ directory.
- * Uses @file references for cross-skill mesh.
+ * Emits SKILL.md files into .cursor/skills/{name}/ directories — Cursor's
+ * native Agent Skills format (Cursor 2.4+, Jan 2026). Skills are loaded
+ * dynamically when the agent decides they're relevant, unlike .cursor/rules
+ * which are always-on context.
+ *
+ * Cursor skills dir: .cursor/skills/
+ * Cursor skill format: .cursor/skills/{name}/SKILL.md
+ * @see https://cursor.com/docs/skills
+ *
+ * NOTE: .cursor/rules/ is still used by the runtime-hooks installer
+ * (adapters/hooks/cursor.js) — rules are the correct vehicle for always-on
+ * hook context. Only skill emission moved to .cursor/skills/.
  *
  * MODEL TIER MAPPING (v2.15+):
  * No-op. Cursor's Anthropic API integration understands `model: opus|sonnet|haiku`
@@ -19,20 +29,24 @@ const TOOL_MAP = {
   Grep: 'search file contents',
   Bash: 'run a terminal command',
   TodoWrite: 'track progress',
-  Skill: 'follow the referenced skill rules',
+  Skill: 'invoke the named skill',
   Agent: 'execute the workflow',
 };
 
 export default {
   name: 'cursor',
-  outputDir: '.cursor/rules',
-  fileExtension: '.mdc',
+  outputDir: '.cursor/skills',
+  fileExtension: '.md',
   skillPrefix: 'rune-',
   skillSuffix: '',
 
+  // Cursor uses directory-per-skill: .cursor/skills/{name}/SKILL.md
+  useSkillDirectories: true,
+  skillFileName: 'SKILL.md',
+
   transformReference(skillName, raw) {
     const isBackticked = raw.startsWith('`') && raw.endsWith('`');
-    const ref = `@rune-${skillName}.mdc`;
+    const ref = `the rune-${skillName} skill`;
     return isBackticked ? `\`${ref}\`` : ref;
   },
 
@@ -41,14 +55,8 @@ export default {
   },
 
   generateHeader(skill) {
-    return [
-      '---',
-      `description: "${skill.description}"`,
-      'globs: []',
-      `alwaysApply: ${skill.layer === 'L0'}`,
-      '---',
-      '',
-    ].join('\n');
+    const desc = (skill.description || '').replace(/"/g, '\\"');
+    return ['---', `name: rune-${skill.name}`, `description: "${desc}"`, '---', '', ''].join('\n');
   },
 
   generateFooter() {
@@ -60,7 +68,7 @@ export default {
   },
 
   scriptsDir(skillName) {
-    return `rune-${skillName}-scripts`;
+    return `rune-${skillName}/scripts`;
   },
 
   postProcess(content) {

package/compiler/adapters/gemini.js

@@ -1,27 +1,25 @@
 /**
  * Gemini CLI Adapter
  *
- * Gemini CLI loads a single GEMINI.md at project root for context. It does NOT
- * support per-skill imports as of writing — so the canonical output is a
- * bundled GEMINI.md with every skill concatenated under `## rune-<name>` H2
- * sections. Per-skill files are still emitted under gemini/skills/ for human
- * inspection and forward-compatibility if Gemini adds @import support later.
+ * Emits SKILL.md files into .gemini/skills/{name}/ directories — Gemini CLI's
+ * native Agent Skills format. Gemini CLI discovers skills automatically from
+ * .gemini/skills/ (and the .agents/skills/ interop alias) and lazy-loads the
+ * full SKILL.md only when a skill is invoked — no more bundling every skill
+ * into GEMINI.md (which loaded all 65 skills as always-on context).
  *
- * Gemini context file: GEMINI.md (project root)
- * Gemini per-skill files: gemini/skills/rune-{name}.md (forward-compat staging)
+ * Gemini skills dir: .gemini/skills/
+ * Gemini skill format: .gemini/skills/{name}/SKILL.md
+ * Gemini project context: GEMINI.md (slim pointer, project root)
  *
- * @see https://github.com/google-gemini/gemini-cli
- * @see https://geminicli.com/docs/reference/configuration/
+ * @see https://geminicli.com/docs/cli/skills/
+ * @see https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/skills.md
  *
  * MODEL TIER MAPPING (v2.18+):
- * Gemini CLI exposes 1.5 Pro / 1.5 Flash / 2.0 Flash etc. Anthropic tier names
- * translate to Gemini families: opus→1.5-pro, sonnet→1.5-flash, haiku→
- * 2.0-flash-lite. Hint only — Gemini CLI reads model from --model flag /
- * config, not from rule body.
+ * Gemini CLI exposes Pro / Flash / Flash-Lite families. Anthropic tier names
+ * translate to Gemini families as a hint comment — Gemini CLI reads model
+ * from --model flag / config, not from the skill body.
  */
 
-import { readFile } from 'node:fs/promises';
-import nodePath from 'node:path';
 import { BRANDING_FOOTER } from '../transforms/branding.js';
 
 const MODEL_MAP = {
@@ -38,23 +36,24 @@ const TOOL_MAP = {
   Grep: 'search file contents',
   Bash: 'run a shell command',
   TodoWrite: 'track task progress',
-  Skill: 'follow the referenced rune-{name} section in GEMINI.md',
+  Skill: 'invoke the rune-{name} skill',
   Agent: 'execute the workflow',
 };
 
 export default {
   name: 'gemini',
-  outputDir: 'gemini/skills',
+  outputDir: '.gemini/skills',
   fileExtension: '.md',
   skillPrefix: 'rune-',
   skillSuffix: '',
 
-  // Per-skill files staged for forward compat; canonical entry is bundled GEMINI.md.
-  useSkillDirectories: false,
+  // Gemini CLI uses directory-per-skill: .gemini/skills/{name}/SKILL.md
+  useSkillDirectories: true,
+  skillFileName: 'SKILL.md',
 
   transformReference(skillName, raw) {
     const isBackticked = raw.startsWith('`') && raw.endsWith('`');
-    const ref = `the rune-${skillName} section in GEMINI.md`;
+    const ref = `the rune-${skillName} skill`;
     return isBackticked ? `\`${ref}\`` : ref;
   },
 
@@ -80,46 +79,24 @@ export default {
   },
 
   scriptsDir(skillName) {
-    return `rune-${skillName}-scripts`;
+    return `rune-${skillName}/scripts`;
   },
 
   postProcess(content) {
     return content.replace(/^context: fork\n/gm, '').replace(/^agent: general-purpose\n/gm, '');
   },
 
-  // Bundle every per-skill file into a single GEMINI.md with H2 section per skill.
-  // Gemini CLI loads GEMINI.md from project root as its context file. Hook contract
-  // requires relative paths (resolved against outputRoot by the emitter).
-  async generateExtraFiles({ stats, outputDir }) {
-    const skillFiles = [...stats.files]
-      .filter((f) => f.startsWith('rune-') && f.endsWith('.md') && !f.includes('/') && !f.includes('\\'))
-      .sort();
-
-    const sections = [];
-    for (const fname of skillFiles) {
-      const sourcePath = nodePath.join(outputDir, fname);
-      try {
-        const raw = await readFile(sourcePath, 'utf-8');
-        // Strip frontmatter — Gemini reads plain markdown.
-        const stripped = raw.replace(/^---\n[\s\S]*?\n---\n?/, '').trim();
-        const skillName = fname.replace(/^rune-/, '').replace(/\.md$/, '');
-        sections.push(`\n\n## rune-${skillName}\n\n${stripped}`);
-      } catch {
-        // Skip unreadable per-skill file — sections array still produces valid bundle.
-      }
-    }
-
+  // Slim GEMINI.md pointer — skills themselves are lazy-loaded natively.
+  generateExtraFiles({ stats }) {
     const geminiMd = [
       '# Rune — Project Configuration',
       '',
       'Rune is an interconnected skill ecosystem for AI coding assistants.',
-      `${stats.skillCount} core skills + ${stats.packCount} extension packs, bundled below.`,
-      '',
-      'When a user request matches a skill\'s domain (e.g. "implement", "review", "debug"), follow the matching `## rune-<name>` section.',
+      `${stats.skillCount} core skills + ${stats.packCount} extension packs.`,
       '',
-      '> Per-skill files are staged in `gemini/skills/` for forward-compat if Gemini CLI adds @import support.',
+      'Per-skill Agent Skills live under `.gemini/skills/rune-<name>/SKILL.md`. Gemini CLI discovers and lazy-loads them automatically.',
       '',
-      ...sections,
+      'When a user request matches a skill\'s domain (e.g. "implement", "review", "debug"), invoke the matching rune-<name> skill.',
       '',
       '---',
       '> Rune Skill Mesh — https://github.com/rune-kit/rune',

package/compiler/adapters/qoder.js

@@ -1,14 +1,15 @@
 /**
  * Qoder Adapter
  *
- * Emits per-skill rule files into .qoder/rules/ — Qoder's documented project-level
- * rule directory. Qoder also reads AGENTS.md as its project-context file.
+ * Emits SKILL.md files into .qoder/skills/{name}/ directories — Qoder's
+ * documented project-level Agent Skills location (works identically in
+ * Qoder IDE and CLI). Qoder also reads AGENTS.md as its project-context file.
  *
- * Qoder rules dir: .qoder/rules/
- * Qoder rule file: .qoder/rules/rune-{name}.md (one file per skill)
+ * Qoder skills dir: .qoder/skills/
+ * Qoder skill format: .qoder/skills/{name}/SKILL.md
  * Qoder project context: AGENTS.md (open AGENTS.md standard)
  *
- * @see https://docs.qoder.com/user-guide/rules
+ * @see https://docs.qoder.com/extensions/skills
  * @see https://agents.md/
  *
  * MODEL TIER MAPPING (v2.18+):
@@ -32,23 +33,24 @@ const TOOL_MAP = {
   Grep: 'search file contents',
   Bash: 'run a shell command',
   TodoWrite: 'track task progress',
-  Skill: 'follow the referenced rune-{name} rule',
+  Skill: 'invoke the rune-{name} skill',
   Agent: 'execute the workflow',
 };
 
 export default {
   name: 'qoder',
-  outputDir: '.qoder/rules',
+  outputDir: '.qoder/skills',
   fileExtension: '.md',
   skillPrefix: 'rune-',
   skillSuffix: '',
 
-  // Qoder rules are flat .md files, not directory-per-skill
-  useSkillDirectories: false,
+  // Qoder uses directory-per-skill: .qoder/skills/{name}/SKILL.md
+  useSkillDirectories: true,
+  skillFileName: 'SKILL.md',
 
   transformReference(skillName, raw) {
     const isBackticked = raw.startsWith('`') && raw.endsWith('`');
-    const ref = `the rune-${skillName} rule`;
+    const ref = `the rune-${skillName} skill`;
     return isBackticked ? `\`${ref}\`` : ref;
   },
 
@@ -74,7 +76,7 @@ export default {
   },
 
   scriptsDir(skillName) {
-    return `rune-${skillName}-scripts`;
+    return `rune-${skillName}/scripts`;
   },
 
   postProcess(content) {
@@ -89,9 +91,7 @@ export default {
       'Rune is an interconnected skill ecosystem for AI coding assistants.',
       `${stats.skillCount} core skills + ${stats.packCount} extension packs.`,
       '',
-      'Per-skill rules live under `.qoder/rules/rune-<name>.md`. Qoder loads them automatically.',
-      '',
-      'Reference a skill by name (e.g. "follow the rune-cook rule") inside any chat — the rule file is auto-injected.',
+      'Per-skill Agent Skills live under `.qoder/skills/rune-<name>/SKILL.md`. Qoder discovers and loads them on demand.',
       '',
       '---',
       '> Rune Skill Mesh — https://github.com/rune-kit/rune',

package/compiler/adapters/qwen.js

@@ -1,15 +1,16 @@
 /**
  * Qwen Coder Adapter
  *
- * Emits per-skill rule files into qwen/skills/ and a top-level QWEN.md that
- * uses Qwen Code's @import syntax to load each rule file. Qwen Code loads
- * QWEN.md hierarchically (cwd → parent → ~/.qwen/QWEN.md).
+ * Emits SKILL.md files into .qwen/skills/{name}/ directories — Qwen Code's
+ * native Agent Skills format. Qwen Code discovers project skills from
+ * .qwen/skills/ and lazy-loads them on demand (browse via /skills) — no more
+ * QWEN.md @import lines that loaded every skill as always-on context.
  *
- * Qwen rules dir: qwen/skills/
- * Qwen rule file: qwen/skills/rune-{name}.md
- * Qwen project context: QWEN.md at project root (with @path imports)
+ * Qwen skills dir: .qwen/skills/
+ * Qwen skill format: .qwen/skills/{name}/SKILL.md
+ * Qwen project context: QWEN.md (slim pointer, loaded hierarchically)
  *
- * @see https://qwenlm.github.io/qwen-code-docs/en/users/configuration/settings/
+ * @see https://qwenlm.github.io/qwen-code-docs/en/users/features/skills/
  * @see https://github.com/QwenLM/qwen-code
  *
  * MODEL TIER MAPPING (v2.18+):
@@ -34,19 +35,20 @@ const TOOL_MAP = {
   Grep: 'search file contents',
   Bash: 'run a shell command',
   TodoWrite: 'track task progress',
-  Skill: 'follow the imported rune-{name} skill',
+  Skill: 'invoke the rune-{name} skill',
   Agent: 'execute the workflow',
 };
 
 export default {
   name: 'qwen',
-  outputDir: 'qwen/skills',
+  outputDir: '.qwen/skills',
   fileExtension: '.md',
   skillPrefix: 'rune-',
   skillSuffix: '',
 
-  // Qwen skills are flat per-skill markdown files imported from QWEN.md.
-  useSkillDirectories: false,
+  // Qwen Code uses directory-per-skill: .qwen/skills/{name}/SKILL.md
+  useSkillDirectories: true,
+  skillFileName: 'SKILL.md',
 
   transformReference(skillName, raw) {
     const isBackticked = raw.startsWith('`') && raw.endsWith('`');
@@ -76,30 +78,22 @@ export default {
   },
 
   scriptsDir(skillName) {
-    return `rune-${skillName}-scripts`;
+    return `rune-${skillName}/scripts`;
   },
 
   postProcess(content) {
     return content.replace(/^context: fork\n/gm, '').replace(/^agent: general-purpose\n/gm, '');
   },
 
-  // Emit QWEN.md at project root with @import lines for every per-skill file.
+  // Slim QWEN.md pointer — skills themselves are lazy-loaded natively.
   generateExtraFiles({ stats }) {
-    const skillFiles = stats.files
-      .filter((f) => f.startsWith('rune-') && f.endsWith('.md') && !f.includes('/') && !f.includes('\\'))
-      .sort();
-
     const qwenMd = [
       '# Rune — Project Configuration',
       '',
       'Rune is an interconnected skill ecosystem for AI coding assistants.',
       `${stats.skillCount} core skills + ${stats.packCount} extension packs.`,
       '',
-      '## Loaded Skills',
-      '',
-      'Qwen Code loads each referenced file as part of this project context.',
-      '',
-      ...skillFiles.map((f) => `@qwen/skills/${f}`),
+      'Per-skill Agent Skills live under `.qwen/skills/rune-<name>/SKILL.md`. Qwen Code discovers and lazy-loads them on demand (browse via /skills).',
       '',
       '---',
       '> Rune Skill Mesh — https://github.com/rune-kit/rune',

package/compiler/adapters/windsurf.js

@@ -1,8 +1,18 @@
 /**
  * Windsurf Adapter
  *
- * Emits .md rule files for .windsurf/rules/ directory.
- * Uses prose references for cross-skill mesh (no @file support).
+ * Emits SKILL.md files into .windsurf/skills/{name}/ directories — Windsurf's
+ * native Cascade Skills format. Cascade uses progressive disclosure: only the
+ * skill's name and description are shown to the model by default; the full
+ * SKILL.md is loaded when Cascade invokes the skill (or via @skill-name).
+ *
+ * Windsurf skills dir: .windsurf/skills/
+ * Windsurf skill format: .windsurf/skills/{name}/SKILL.md
+ * @see https://docs.windsurf.com/windsurf/cascade/skills
+ *
+ * NOTE: .windsurf/rules/ is still used by the runtime-hooks installer
+ * (adapters/hooks/windsurf.js) — rules are the correct vehicle for always-on
+ * hook context. Only skill emission moved to .windsurf/skills/.
  *
  * MODEL TIER MAPPING (v2.15+):
  * No-op. Windsurf's Anthropic API integration understands `model: opus|sonnet|haiku`
@@ -19,20 +29,24 @@ const TOOL_MAP = {
   Grep: 'search for text in files',
   Bash: 'run a shell command',
   TodoWrite: 'track task progress',
-  Skill: 'follow the referenced skill workflow',
+  Skill: 'invoke the named skill',
   Agent: 'execute the workflow',
 };
 
 export default {
   name: 'windsurf',
-  outputDir: '.windsurf/rules',
+  outputDir: '.windsurf/skills',
   fileExtension: '.md',
   skillPrefix: 'rune-',
   skillSuffix: '',
 
+  // Windsurf uses directory-per-skill: .windsurf/skills/{name}/SKILL.md
+  useSkillDirectories: true,
+  skillFileName: 'SKILL.md',
+
   transformReference(skillName, raw) {
     const isBackticked = raw.startsWith('`') && raw.endsWith('`');
-    const ref = `the rune-${skillName} rule file`;
+    const ref = `the rune-${skillName} skill`;
     return isBackticked ? `\`${ref}\`` : ref;
   },
 
@@ -41,7 +55,8 @@ export default {
   },
 
   generateHeader(skill) {
-    return `# rune-${skill.name}\n\n> Layer: ${skill.layer} | Group: ${skill.group}\n\n`;
+    const desc = (skill.description || '').replace(/"/g, '\\"');
+    return ['---', `name: rune-${skill.name}`, `description: "${desc}"`, '---', '', ''].join('\n');
   },
 
   generateFooter() {
@@ -53,7 +68,7 @@ export default {
   },
 
   scriptsDir(skillName) {
-    return `rune-${skillName}-scripts`;
+    return `rune-${skillName}/scripts`;
   },
 
   postProcess(content) {

package/compiler/emitter.js

@@ -65,7 +65,7 @@ async function discoverPacks(extensionsDir, enabledPacks = null) {
  * Copies directories except SKILL.md (already processed) and denylisted dirs
  *
  * @param {string} sourceSkillDir - e.g. skills/cook/
- * @param {string} outputSkillDir - e.g. .codex/skills/rune-cook/
+ * @param {string} outputSkillDir - e.g. .agents/skills/rune-cook/
  * @returns {Promise<string[]>} list of copied directory names
  */
 const COPY_DENYLIST = new Set(['.git', 'node_modules', '__pycache__', '.DS_Store', '.venv', '.env']);
@@ -74,7 +74,8 @@ async function copySkillExtraDirs(sourceSkillDir, outputSkillDir) {
   if (!existsSync(sourceSkillDir)) return [];
 
   const entries = await readdir(sourceSkillDir, { withFileTypes: true });
-  const dirs = entries.filter((e) => e.isDirectory() && !COPY_DENYLIST.has(e.name));
+  // scripts/ is excluded: copyScriptsDir handles it explicitly (with stats counting)
+  const dirs = entries.filter((e) => e.isDirectory() && !COPY_DENYLIST.has(e.name) && e.name !== 'scripts');
 
   const copied = [];
   for (const dir of dirs) {
@@ -91,7 +92,7 @@ async function copySkillExtraDirs(sourceSkillDir, outputSkillDir) {
  * Copy scripts directory from skill source to output.
  *
  * @param {string} sourceScriptsDir - e.g. skills/slides/scripts/
- * @param {string} outputScriptsDir - e.g. .cursor/rules/rune-slides-scripts/
+ * @param {string} outputScriptsDir - e.g. .cursor/skills/rune-slides/scripts/
  * @returns {Promise<string[]>} list of copied file paths
  */
 async function copyScriptsDir(sourceScriptsDir, outputScriptsDir) {
@@ -524,7 +525,7 @@ export async function buildAll({
       let skillDir = null;
 
       if (adapter.useSkillDirectories) {
-        // Directory-per-skill: .codex/skills/rune-{name}/SKILL.md
+        // Directory-per-skill: .agents/skills/rune-{name}/SKILL.md
         const dirName = `${adapter.skillPrefix}${parsed.name}`;
         skillDir = path.join(outputDir, dirName);
         await mkdir(skillDir, { recursive: true });

package/compiler/parser.js

@@ -34,6 +34,15 @@ function parseFrontmatter(content) {
   let nestedKey = null;
   const _nestedObj = {};
 
+  // Strip outer quotes; for double-quoted scalars also unescape interior \"
+  // so consumers (adapter generateHeader) hold clean text and can re-escape
+  // exactly once. Without this, `\"` survives into skill.description and a
+  // later .replace(/"/g, '\\"') turns it into `\\"` — invalid YAML.
+  const parseScalar = (rawValue) => {
+    const stripped = rawValue.replace(/^["']|["']$/g, '');
+    return rawValue.startsWith('"') ? stripped.replace(/\\"/g, '"') : stripped;
+  };
+
   for (const line of raw.split('\n')) {
     const trimmed = line.trim();
     if (!trimmed) continue;
@@ -60,7 +69,7 @@ function parseFrontmatter(content) {
 
       const kvMatch = trimmed.match(/^(\w[\w-]*):\s*(.+)$/);
       if (kvMatch) {
-        const rawValue = kvMatch[2].replace(/^["']|["']$/g, '');
+        const rawValue = parseScalar(kvMatch[2]);
         // Comma-separated list fields → parse as array
         if (COMMA_LIST_FIELDS.has(kvMatch[1])) {
           frontmatter[nestedKey][kvMatch[1]] = rawValue
@@ -79,7 +88,7 @@ function parseFrontmatter(content) {
     nestedKey = null;
     const kvMatch = trimmed.match(/^(\w[\w-]*):\s*(.+)$/);
     if (kvMatch) {
-      const value = kvMatch[2].replace(/^["']|["']$/g, '');
+      const value = parseScalar(kvMatch[2]);
       // Comma-separated list fields at top level too (Pro/Business packs)
       if (COMMA_LIST_FIELDS.has(kvMatch[1])) {
         frontmatter[kvMatch[1]] = value

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rune-kit/rune",
-  "version": "2.22.2",
+  "version": "2.23.0",
   "description": "65-skill mesh for AI coding assistants — runtime auto-discipline via native hooks (Claude/Cursor/Windsurf/Antigravity), 5-layer architecture, 204 connections + 43 signals, multi-platform compiler. converge (L3) scans spec vs code so dead-button/frontend-only implementations can't ship.",
   "type": "module",
   "bin": {