skiller 0.8.2 → 0.9.0

package/dist/core/SkillsProcessor.js

@@ -34,6 +34,9 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isReferenceBody = isReferenceBody;
+exports.extractLocalRulesFromCanonicalSkills = extractLocalRulesFromCanonicalSkills;
+exports.compileRulesToSkills = compileRulesToSkills;
+exports.normalizeCanonicalSkills = normalizeCanonicalSkills;
 exports.syncMdcToSkillMd = syncMdcToSkillMd;
 exports.discoverSkills = discoverSkills;
 exports.copySkillsToAgent = copySkillsToAgent;
@@ -49,8 +52,74 @@ const yaml = __importStar(require("js-yaml"));
 const constants_1 = require("../constants");
 const SkillsUtils_1 = require("./SkillsUtils");
 const FrontmatterParser_1 = require("./FrontmatterParser");
+const SkillOwnership_1 = require("./SkillOwnership");
 const LEGACY_CODEX_SKILLS_PATH = path.join('.codex', 'skills');
 const UNIVERSAL_AGENTS_SKILLS_PATH = path.join('.agents', 'skills');
+async function pathExists(targetPath) {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function resolveProjectSkillsDir(projectRoot, skillerDir) {
+    if (skillerDir)
+        return path.join(skillerDir, 'skills');
+    const canonicalSkillsDir = path.join(projectRoot, '.agents', 'skills');
+    if (await pathExists(canonicalSkillsDir)) {
+        return canonicalSkillsDir;
+    }
+    const legacySkillsDir = path.join(projectRoot, '.claude', 'skills');
+    if (await pathExists(legacySkillsDir)) {
+        return legacySkillsDir;
+    }
+    return canonicalSkillsDir;
+}
+async function skillFolderContainsMdc(dir, depth = 0) {
+    if (depth >= constants_1.MAX_RECURSION_DEPTH)
+        return false;
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isFile() && entry.name.endsWith('.mdc')) {
+            return true;
+        }
+        if (entry.isDirectory()) {
+            const nestedHasMdc = await skillFolderContainsMdc(fullPath, depth + 1);
+            if (nestedHasMdc)
+                return true;
+        }
+    }
+    return false;
+}
+async function skillCanBeSymlinked(skillPath) {
+    const skillMdPath = path.join(skillPath, constants_1.SKILL_MD_FILENAME);
+    let skillMdContent;
+    try {
+        skillMdContent = await fs.readFile(skillMdPath, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    if (isReferenceBody((0, FrontmatterParser_1.parseFrontmatter)(skillMdContent).body).isReference) {
+        return false;
+    }
+    return !(await skillFolderContainsMdc(skillPath));
+}
+async function createRelativeDirectorySymlink(sourceDir, targetDir) {
+    try {
+        await fs.rm(targetDir, { recursive: true, force: true });
+        await fs.mkdir(path.dirname(targetDir), { recursive: true });
+        const relativeTarget = path.relative(path.dirname(targetDir), sourceDir);
+        await fs.symlink(relativeTarget, targetDir, 'junction');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * For non-Claude agents, compile a wrapper SKILL.md (body is a single @reference)
  * into a standalone SKILL.md with the referenced file's body inlined.
@@ -59,30 +128,14 @@ const UNIVERSAL_AGENTS_SKILLS_PATH = path.join('.agents', 'skills');
  * an @reference line, to avoid accidentally treating email addresses or
  * "@mentions" inside real content as file references.
  */
-async function compileSkillMdForNonClaudeAgents(skillMdContent, projectRoot, skillFolderPath) {
+async function compileSkillMdForNonClaudeAgents(skillMdContent, projectRoot, skillFolderPath, options = {}) {
     const { frontmatter, rawFrontmatter, body } = (0, FrontmatterParser_1.parseFrontmatter)(skillMdContent);
-    const refCheck = isReferenceBody(body);
-    if (!refCheck.isReference || !refCheck.referencePath) {
-        return skillMdContent;
-    }
-    const referencePath = refCheck.referencePath;
-    const absoluteRefPath = referencePath.startsWith('./') || referencePath.startsWith('../')
-        ? path.resolve(skillFolderPath, referencePath)
-        : path.resolve(projectRoot, referencePath);
-    // Security: only inline references within the project root.
-    const normalizedProjectRoot = path.resolve(projectRoot);
-    const normalizedAbsoluteRefPath = path.resolve(absoluteRefPath);
-    if (!normalizedAbsoluteRefPath.startsWith(normalizedProjectRoot + path.sep)) {
-        return skillMdContent;
-    }
-    let referencedContent;
-    try {
-        referencedContent = await fs.readFile(normalizedAbsoluteRefPath, 'utf8');
-    }
-    catch {
+    const compiledBodyResult = await inlineReferenceDirectives(body, projectRoot, options.baseFilePath ?? path.join(skillFolderPath, constants_1.SKILL_MD_FILENAME), {
+        fallbackReferenceDir: options.fallbackReferenceDir,
+    });
+    if (!compiledBodyResult.changed) {
         return skillMdContent;
     }
-    const { body: referencedBody } = (0, FrontmatterParser_1.parseFrontmatter)(referencedContent);
     const fmData = rawFrontmatter && Object.keys(rawFrontmatter).length > 0
         ? rawFrontmatter
         : frontmatter && Object.keys(frontmatter).length > 0
@@ -93,10 +146,10 @@ async function compileSkillMdForNonClaudeAgents(skillMdContent, projectRoot, ski
 ${yaml.dump(fmData, { lineWidth: -1, noRefs: true }).trim()}
 ---
 
-${referencedBody}
+${compiledBodyResult.body}
 `;
     }
-    return `${referencedBody}\n`;
+    return `${compiledBodyResult.body}\n`;
 }
 /**
  * Copies a single skill directory to an agent skill directory:
@@ -151,301 +204,493 @@ function isReferenceBody(body) {
     }
     return { isReference: false };
 }
-/**
- * Bidirectional sync between .mdc files and SKILL.md in the skills directory.
- *
- * Sync logic (using @reference pattern instead of synced: true):
- * 1. If sibling .mdc exists (name/name.mdc) but no SKILL.md → generate SKILL.md with @./name.mdc
- * 2. If SKILL.md body is @reference → referenced file is source of truth
- * 3. If SKILL.md has full content → generate sibling .mdc, update SKILL.md to @./name.mdc
- *
- * File structure:
- * - .claude/skills/foo/foo.mdc → .claude/skills/foo/SKILL.md (with @./foo.mdc body)
- *
- * Backward compatibility:
- * - .claude/skills/foo.mdc at root → migrates to sibling pattern
- * - @.claude/rules/name.mdc → recognized as reference (pre-0.7 pattern)
- */
-async function syncMdcToSkillMd(skillsDir, verbose, dryRun) {
-    const synced = [];
+function parseReferenceDirectiveLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('@'))
+        return null;
+    const raw = trimmed.slice(1);
+    const hashIndex = raw.indexOf('#');
+    const pathPart = (hashIndex === -1 ? raw : raw.slice(0, hashIndex)).trim();
+    const fragment = hashIndex === -1 ? undefined : raw.slice(hashIndex + 1).trim() || undefined;
+    const looksLikePath = pathPart.startsWith('./') ||
+        pathPart.startsWith('../') ||
+        pathPart.startsWith('.agents/') ||
+        pathPart.startsWith('.claude/') ||
+        pathPart.includes('/') ||
+        /\.[A-Za-z0-9_-]+$/.test(pathPart);
+    if (!looksLikePath)
+        return null;
+    return { pathPart, fragment };
+}
+function slugifyHeading(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[`*_~]/g, '')
+        .replace(/[^\p{L}\p{N}\s-]/gu, '')
+        .replace(/\s+/g, '-')
+        .replace(/-+/g, '-');
+}
+function extractMarkdownFragment(body, fragment) {
+    if (!fragment)
+        return body;
+    const lines = body.split('\n');
+    const target = fragment.trim();
+    const targetSlug = slugifyHeading(target);
+    let startIndex = -1;
+    let headingLevel = 0;
+    for (let index = 0; index < lines.length; index += 1) {
+        const match = /^(#{1,6})\s+(.*)$/.exec(lines[index].trim());
+        if (!match)
+            continue;
+        const headingText = match[2].trim();
+        if (headingText === target || slugifyHeading(headingText) === targetSlug) {
+            startIndex = index + 1;
+            headingLevel = match[1].length;
+            break;
+        }
+    }
+    if (startIndex === -1)
+        return body;
+    let endIndex = lines.length;
+    for (let index = startIndex; index < lines.length; index += 1) {
+        const match = /^(#{1,6})\s+/.exec(lines[index].trim());
+        if (match && match[1].length <= headingLevel) {
+            endIndex = index;
+            break;
+        }
+    }
+    return lines.slice(startIndex, endIndex).join('\n').trim();
+}
+async function readReferenceDirectiveContent(projectRoot, baseFilePath, directive, options) {
+    const candidates = [];
+    const { pathPart, fragment } = directive;
+    if (pathPart.startsWith('./') || pathPart.startsWith('../')) {
+        candidates.push(path.resolve(path.dirname(baseFilePath), pathPart));
+        if (options.fallbackReferenceDir) {
+            candidates.push(path.resolve(options.fallbackReferenceDir, pathPart));
+        }
+    }
+    else {
+        candidates.push(path.resolve(projectRoot, pathPart));
+    }
+    let resolvedPath = null;
+    for (const candidate of candidates) {
+        try {
+            await fs.access(candidate);
+            resolvedPath = candidate;
+            break;
+        }
+        catch {
+            // Try next candidate.
+        }
+    }
+    if (!resolvedPath)
+        return null;
+    const visitKey = `${resolvedPath}#${fragment ?? ''}`;
+    if (options.visited.has(visitKey)) {
+        return null;
+    }
+    options.visited.add(visitKey);
+    try {
+        const rawContent = await fs.readFile(resolvedPath, 'utf8');
+        const extension = path.extname(resolvedPath).toLowerCase();
+        if (extension === '.md' || extension === '.mdc') {
+            const parsed = (0, FrontmatterParser_1.parseFrontmatter)(rawContent);
+            const nested = await inlineReferenceDirectives(parsed.body, projectRoot, resolvedPath, {
+                fallbackReferenceDir: path.dirname(resolvedPath),
+                visited: options.visited,
+                depth: options.depth + 1,
+            });
+            return extractMarkdownFragment(nested.body, fragment);
+        }
+        return rawContent.trim();
+    }
+    finally {
+        options.visited.delete(visitKey);
+    }
+}
+async function inlineReferenceDirectives(body, projectRoot, baseFilePath, options = {}) {
+    const depth = options.depth ?? 0;
+    if (depth >= constants_1.MAX_RECURSION_DEPTH) {
+        return { body, changed: false };
+    }
+    const visited = options.visited ?? new Set();
+    const lines = body.split('\n');
+    const output = [];
+    let changed = false;
+    for (const line of lines) {
+        const directive = parseReferenceDirectiveLine(line);
+        if (!directive) {
+            output.push(line);
+            continue;
+        }
+        const referencedContent = await readReferenceDirectiveContent(projectRoot, baseFilePath, directive, {
+            fallbackReferenceDir: options.fallbackReferenceDir,
+            visited,
+            depth,
+        });
+        if (referencedContent === null) {
+            output.push(line);
+            continue;
+        }
+        changed = true;
+        output.push(referencedContent.trimEnd());
+    }
+    return {
+        body: output.join('\n'),
+        changed,
+    };
+}
+function toProjectRelative(projectRoot, targetPath) {
+    return path.relative(projectRoot, targetPath).replace(/\\/g, '/');
+}
+function cloneRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? { ...value }
+        : {};
+}
+function buildCanonicalSkillFrontmatter(skillName, rawFrontmatter, options = {}) {
+    const next = rawFrontmatter ? { ...rawFrontmatter } : {};
+    delete next.globs;
+    delete next.alwaysApply;
+    next.name = skillName;
+    if (typeof next.description !== 'string' ||
+        next.description.trim().length === 0) {
+        next.description = `Skill: ${skillName}`;
+    }
+    const metadata = cloneRecord(next.metadata);
+    const skillerMeta = cloneRecord(metadata.skiller);
+    if (options.sourceRelPath) {
+        skillerMeta.source = options.sourceRelPath;
+    }
+    if (options.alwaysApply === true) {
+        skillerMeta.alwaysApply = true;
+    }
+    else {
+        delete skillerMeta.alwaysApply;
+    }
+    if (Object.keys(skillerMeta).length > 0) {
+        metadata.skiller = skillerMeta;
+    }
+    else {
+        delete metadata.skiller;
+    }
+    if (Object.keys(metadata).length > 0) {
+        next.metadata = metadata;
+    }
+    else {
+        delete next.metadata;
+    }
+    return next;
+}
+function buildCanonicalSkillContent(skillName, rawFrontmatter, body, options = {}) {
+    const frontmatter = buildCanonicalSkillFrontmatter(skillName, rawFrontmatter, options);
+    return `---
+${yaml.dump(frontmatter, { lineWidth: -1, noRefs: true }).trim()}
+---
+
+${body.trim()}
+`;
+}
+function buildRuleSourceContent(rawFrontmatter, body) {
+    const next = rawFrontmatter ? { ...rawFrontmatter } : {};
+    delete next.name;
+    delete next.globs;
+    const metadata = cloneRecord(next.metadata);
+    const skillerMeta = cloneRecord(metadata.skiller);
+    const alwaysApply = skillerMeta.alwaysApply === true;
+    delete skillerMeta.source;
+    delete skillerMeta.alwaysApply;
+    if (Object.keys(skillerMeta).length > 0) {
+        metadata.skiller = skillerMeta;
+    }
+    else {
+        delete metadata.skiller;
+    }
+    if (Object.keys(metadata).length > 0) {
+        next.metadata = metadata;
+    }
+    else {
+        delete next.metadata;
+    }
+    if (alwaysApply) {
+        next.alwaysApply = true;
+    }
+    if (Object.keys(next).length === 0) {
+        return `${body.trim()}\n`;
+    }
+    return `---
+${yaml.dump(next, { lineWidth: -1, noRefs: true }).trim()}
+---
+
+${body.trim()}
+`;
+}
+function flattenNestedFrontmatter(rawFrontmatter, body) {
+    const nested = (0, FrontmatterParser_1.parseFrontmatter)(body);
+    if (!nested.rawFrontmatter) {
+        return { rawFrontmatter, body };
+    }
+    return {
+        rawFrontmatter: {
+            ...(rawFrontmatter ?? {}),
+            ...nested.rawFrontmatter,
+        },
+        body: nested.body,
+    };
+}
+function normalizeRuleSourceContent(content) {
+    const parsed = (0, FrontmatterParser_1.parseFrontmatter)(content);
+    const flattened = flattenNestedFrontmatter(parsed.rawFrontmatter, parsed.body);
+    return buildRuleSourceContent(flattened.rawFrontmatter, flattened.body);
+}
+function resolveSkillReferencePath(projectRoot, skillFolderPath, referencePath) {
+    return referencePath.startsWith('./') || referencePath.startsWith('../')
+        ? path.resolve(skillFolderPath, referencePath)
+        : path.resolve(projectRoot, referencePath);
+}
+async function readLegacyLocalRuleSource(projectRoot, skillFolderPath, skillMdContent) {
+    const { rawFrontmatter, body } = (0, FrontmatterParser_1.parseFrontmatter)(skillMdContent);
+    const refCheck = isReferenceBody(body);
+    if (refCheck.isReference && refCheck.referencePath) {
+        const referencedPath = resolveSkillReferencePath(projectRoot, skillFolderPath, refCheck.referencePath);
+        return fs.readFile(referencedPath, 'utf8');
+    }
+    const flattened = flattenNestedFrontmatter(rawFrontmatter, body);
+    return buildRuleSourceContent(flattened.rawFrontmatter, flattened.body);
+}
+async function writeFileIfChanged(targetPath, content, dryRun) {
+    try {
+        const existing = await fs.readFile(targetPath, 'utf8');
+        if (existing === content) {
+            return false;
+        }
+    }
+    catch {
+        // Write below.
+    }
+    if (!dryRun) {
+        await fs.mkdir(path.dirname(targetPath), { recursive: true });
+        await fs.writeFile(targetPath, content, 'utf8');
+    }
+    return true;
+}
+async function extractLocalRulesFromCanonicalSkills(projectRoot, verbose, dryRun) {
     const warnings = [];
+    const extracted = [];
+    const skillsDir = path.join(projectRoot, '.agents', 'skills');
+    const rulesDir = path.join(projectRoot, '.agents', 'rules');
+    const ownership = await (0, SkillOwnership_1.resolveSkillOwnership)(projectRoot);
     try {
         await fs.access(skillsDir);
     }
     catch {
-        // Skills directory doesn't exist
-        return { synced, warnings };
+        return { extracted, warnings };
     }
     const entries = await fs.readdir(skillsDir, { withFileTypes: true });
-    // Find .mdc files at skills root (for backward compatibility/migration)
-    const rootMdcFiles = entries.filter((e) => e.isFile() && e.name.endsWith('.mdc'));
-    // First, migrate any root .mdc files to sibling pattern
-    for (const mdcFile of rootMdcFiles) {
-        const skillName = path.basename(mdcFile.name, '.mdc');
-        const rootMdcPath = path.join(skillsDir, mdcFile.name);
+    const adoptedNames = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const skillName = entry.name;
+        if (ownership.upstreamOwned.has(skillName)) {
+            continue;
+        }
+        const rulePath = path.join(rulesDir, `${skillName}.mdc`);
+        try {
+            await fs.access(rulePath);
+            continue;
+        }
+        catch {
+            // No explicit local rule yet; safe to extract below.
+        }
         const skillFolderPath = path.join(skillsDir, skillName);
-        const siblingMdcPath = path.join(skillFolderPath, mdcFile.name);
+        const skillMdPath = path.join(skillFolderPath, constants_1.SKILL_MD_FILENAME);
+        let skillMdContent;
         try {
-            // Create skill folder if needed
-            if (!dryRun) {
-                await fs.mkdir(skillFolderPath, { recursive: true });
-            }
-            // Move .mdc to sibling location
-            if (dryRun) {
-                (0, constants_1.logVerboseInfo)(`DRY RUN: Would migrate ${mdcFile.name} to ${skillName}/${mdcFile.name}`, verbose, dryRun);
-            }
-            else {
-                const mdcContent = await fs.readFile(rootMdcPath, 'utf8');
-                await fs.writeFile(siblingMdcPath, mdcContent, 'utf8');
-                await fs.unlink(rootMdcPath);
-                (0, constants_1.logVerboseInfo)(`Migrated ${mdcFile.name} to ${skillName}/${mdcFile.name}`, verbose, dryRun);
+            skillMdContent = await fs.readFile(skillMdPath, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        try {
+            const ruleContent = await readLegacyLocalRuleSource(projectRoot, skillFolderPath, skillMdContent);
+            const changed = await writeFileIfChanged(rulePath, ruleContent, dryRun);
+            if (changed) {
+                (0, constants_1.logVerboseInfo)(dryRun
+                    ? `DRY RUN: Would extract local skill source ${skillName} to ${toProjectRelative(projectRoot, rulePath)}`
+                    : `Extracted local skill source ${skillName} to ${toProjectRelative(projectRoot, rulePath)}`, verbose, dryRun);
             }
+            extracted.push(skillName);
+            adoptedNames.push(skillName);
         }
         catch (err) {
-            warnings.push(`Failed to migrate ${skillName}.mdc: ${err.message}`);
+            warnings.push(`Failed to extract local rule source for ${skillName}: ${err.message}`);
         }
     }
-    // Re-read entries after migration
-    const updatedEntries = await fs.readdir(skillsDir, { withFileTypes: true });
-    const updatedSkillFolders = updatedEntries.filter((e) => e.isDirectory());
-    // Process skill folders
-    for (const folder of updatedSkillFolders) {
-        const skillName = folder.name;
+    if (adoptedNames.length > 0) {
+        await (0, SkillOwnership_1.adoptSkillerOwnedSkillNames)(projectRoot, adoptedNames, dryRun);
+    }
+    return { extracted, warnings };
+}
+async function compileRulesToSkills(skillerDir, projectRoot, verbose, dryRun) {
+    const warnings = [];
+    const compiled = [];
+    const rulesDir = path.join(skillerDir, 'rules');
+    const skillsDir = path.join(skillerDir, 'skills');
+    const ownership = await (0, SkillOwnership_1.resolveSkillOwnership)(projectRoot);
+    try {
+        await fs.access(rulesDir);
+    }
+    catch {
+        return { compiled, warnings };
+    }
+    const entries = await fs.readdir(rulesDir, { withFileTypes: true });
+    const ruleFiles = entries.filter((entry) => {
+        return entry.isFile() && entry.name.endsWith('.mdc');
+    });
+    const adoptedNames = [];
+    for (const ruleFile of ruleFiles) {
+        const skillName = path.basename(ruleFile.name, '.mdc');
+        if (ownership.upstreamOwned.has(skillName)) {
+            throw new Error(`Local rule '${skillName}' conflicts with upstream-managed skill '${skillName}' in skills-lock.json`);
+        }
+        const sourcePath = path.join(rulesDir, ruleFile.name);
+        const sourceContent = await fs.readFile(sourcePath, 'utf8');
+        const normalizedSourceContent = normalizeRuleSourceContent(sourceContent);
+        if (normalizedSourceContent !== sourceContent) {
+            await writeFileIfChanged(sourcePath, normalizedSourceContent, dryRun);
+        }
+        const parsed = (0, FrontmatterParser_1.parseFrontmatter)(normalizedSourceContent);
         const skillFolderPath = path.join(skillsDir, skillName);
+        const compiledBodyResult = await inlineReferenceDirectives(parsed.body, projectRoot, sourcePath, {
+            fallbackReferenceDir: skillFolderPath,
+        });
+        const compiledContent = buildCanonicalSkillContent(skillName, parsed.rawFrontmatter, compiledBodyResult.body, {
+            sourceRelPath: toProjectRelative(projectRoot, sourcePath),
+            alwaysApply: parsed.frontmatter?.alwaysApply === true,
+        });
         const skillMdPath = path.join(skillFolderPath, constants_1.SKILL_MD_FILENAME);
-        const siblingMdcPath = path.join(skillFolderPath, `${skillName}.mdc`);
-        // Check if sibling .mdc exists
-        let siblingMdcContent = null;
-        try {
-            siblingMdcContent = await fs.readFile(siblingMdcPath, 'utf8');
+        const changed = await writeFileIfChanged(skillMdPath, compiledContent, dryRun);
+        if (!dryRun) {
+            await fs.mkdir(skillFolderPath, { recursive: true });
+            const skillEntries = await fs.readdir(skillFolderPath, {
+                withFileTypes: true,
+            });
+            for (const entry of skillEntries) {
+                if (entry.isFile() && entry.name.endsWith('.mdc')) {
+                    await fs.rm(path.join(skillFolderPath, entry.name), {
+                        force: true,
+                    });
+                }
+            }
         }
-        catch {
-            // No sibling .mdc
+        if (changed) {
+            (0, constants_1.logVerboseInfo)(dryRun
+                ? `DRY RUN: Would compile ${toProjectRelative(projectRoot, sourcePath)} to ${toProjectRelative(projectRoot, skillMdPath)}`
+                : `Compiled ${toProjectRelative(projectRoot, sourcePath)} to ${toProjectRelative(projectRoot, skillMdPath)}`, verbose, dryRun);
         }
-        // Check if SKILL.md exists
+        compiled.push(skillName);
+        adoptedNames.push(skillName);
+    }
+    if (adoptedNames.length > 0) {
+        await (0, SkillOwnership_1.adoptSkillerOwnedSkillNames)(projectRoot, adoptedNames, dryRun);
+    }
+    return { compiled, warnings };
+}
+async function normalizeCanonicalSkills(projectRoot, skillsDir, verbose, dryRun) {
+    const normalized = [];
+    const warnings = [];
+    try {
+        await fs.access(skillsDir);
+    }
+    catch {
+        return { normalized, warnings };
+    }
+    const entries = await fs.readdir(skillsDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const skillName = entry.name;
+        const skillFolderPath = path.join(skillsDir, skillName);
+        const skillMdPath = path.join(skillFolderPath, constants_1.SKILL_MD_FILENAME);
         let skillMdContent = null;
         try {
             skillMdContent = await fs.readFile(skillMdPath, 'utf8');
         }
         catch {
-            // No SKILL.md
+            skillMdContent = null;
         }
-        try {
-            if (siblingMdcContent !== null && skillMdContent === null) {
-                // Case 1: Sibling .mdc exists but no SKILL.md
-                const { frontmatter: mdcFrontmatter } = (0, FrontmatterParser_1.parseFrontmatter)(siblingMdcContent);
-                // Skip SKILL.md generation for .mdc files with alwaysApply: true
-                // These are Cursor-style rules, not Claude Code skills
-                if (mdcFrontmatter?.alwaysApply === true) {
-                    (0, constants_1.logVerboseInfo)(`Skipping SKILL.md generation for ${skillName} (alwaysApply rule)`, verbose, dryRun);
-                    continue;
-                }
-                // Generate SKILL.md with @reference (absolute path)
-                // Keep all frontmatter from .mdc except globs and alwaysApply
-                const skillFrontmatter = {
-                    name: skillName,
-                    ...Object.fromEntries(Object.entries(mdcFrontmatter || {}).filter(([key]) => key !== 'globs' && key !== 'alwaysApply')),
-                };
-                // Ensure description has a default
-                if (!skillFrontmatter.description) {
-                    skillFrontmatter.description = `Skill: ${skillName}`;
-                }
-                const newSkillMd = `---
-${yaml.dump(skillFrontmatter, { lineWidth: -1, noRefs: true }).trim()}
----
-
-@.claude/skills/${skillName}/${skillName}.mdc
-`;
-                if (dryRun) {
-                    (0, constants_1.logVerboseInfo)(`DRY RUN: Would generate ${skillName}/SKILL.md with @reference`, verbose, dryRun);
-                }
-                else {
-                    await fs.writeFile(skillMdPath, newSkillMd, 'utf8');
-                    (0, constants_1.logVerboseInfo)(`Generated ${skillName}/SKILL.md with @.claude/skills/${skillName}/${skillName}.mdc reference`, verbose, dryRun);
+        let changed = false;
+        if (skillMdContent) {
+            const compiled = await compileSkillMdForNonClaudeAgents(skillMdContent, projectRoot, skillFolderPath, {
+                baseFilePath: skillMdPath,
+                fallbackReferenceDir: skillFolderPath,
+            });
+            if (compiled !== skillMdContent) {
+                if (!dryRun) {
+                    await fs.writeFile(skillMdPath, compiled, 'utf8');
                 }
-                synced.push(skillName);
+                changed = true;
             }
-            else if (skillMdContent !== null) {
-                // Check if sibling .mdc has alwaysApply: true - if so, delete SKILL.md
-                if (siblingMdcContent !== null) {
-                    const { frontmatter: mdcFrontmatter } = (0, FrontmatterParser_1.parseFrontmatter)(siblingMdcContent);
-                    if (mdcFrontmatter?.alwaysApply === true) {
-                        // .mdc is now an alwaysApply rule - remove the SKILL.md
-                        if (dryRun) {
-                            (0, constants_1.logVerboseInfo)(`DRY RUN: Would delete ${skillName}/SKILL.md (now alwaysApply rule)`, verbose, dryRun);
-                        }
-                        else {
-                            await fs.unlink(skillMdPath);
-                            (0, constants_1.logVerboseInfo)(`Deleted ${skillName}/SKILL.md (now alwaysApply rule)`, verbose, dryRun);
-                        }
-                        synced.push(skillName);
-                        continue;
-                    }
-                }
-                // SKILL.md exists - check if it's a reference
-                const { frontmatter: skillFrontmatter, rawFrontmatter: skillRawFrontmatter, body: skillBody, } = (0, FrontmatterParser_1.parseFrontmatter)(skillMdContent);
-                const refCheck = isReferenceBody(skillBody);
-                if (refCheck.isReference) {
-                    // Case 2: SKILL.md is @reference → source file is truth
-                    // Check for both relative and absolute sibling reference patterns
-                    const isRelativeSiblingRef = refCheck.referencePath === `./${skillName}.mdc`;
-                    const isAbsoluteSiblingRef = refCheck.referencePath ===
-                        `.claude/skills/${skillName}/${skillName}.mdc`;
-                    if (isRelativeSiblingRef || isAbsoluteSiblingRef) {
-                        // Sibling reference pattern - only migrate path if needed (don't touch frontmatter)
-                        if (isRelativeSiblingRef) {
-                            // Migrate old relative refs to absolute path, preserving existing frontmatter
-                            const newSkillMd = `---
-${yaml.dump(skillFrontmatter || { name: skillName }, { lineWidth: -1, noRefs: true }).trim()}
----
-
-@.claude/skills/${skillName}/${skillName}.mdc
-`;
-                            if (dryRun) {
-                                (0, constants_1.logVerboseInfo)(`DRY RUN: Would migrate ${skillName}/SKILL.md to absolute path`, verbose, dryRun);
-                            }
-                            else {
-                                await fs.writeFile(skillMdPath, newSkillMd, 'utf8');
-                                (0, constants_1.logVerboseInfo)(`Migrated ${skillName}/SKILL.md to absolute path`, verbose, dryRun);
-                            }
-                            synced.push(skillName);
-                        }
-                        // If already absolute path, nothing to do - SKILL.md is source of truth for frontmatter
-                    }
-                    else if (refCheck.referencePath) {
-                        // Pre-0.7 pattern or other external reference - migrate to sibling pattern
-                        // Determine base path for resolution:
-                        // - Paths starting with .claude/ are relative to project root
-                        // - Other paths are relative to the skill folder
-                        let referencedPath;
-                        if (refCheck.referencePath.startsWith('.claude/')) {
-                            // Project root is parent of .claude directory (skillsDir is .claude/skills)
-                            const projectRoot = path.dirname(path.dirname(skillsDir));
-                            referencedPath = path.join(projectRoot, refCheck.referencePath);
-                        }
-                        else {
-                            referencedPath = path.resolve(skillFolderPath, refCheck.referencePath);
-                        }
-                        // One-time migration: for old @.claude/rules/ references, prefer the
-                        // original rules path if it exists, then fall back to migrated skills.
-                        const candidatePaths = [referencedPath];
-                        if (refCheck.referencePath?.includes('/rules/')) {
-                            const refFileName = path.basename(refCheck.referencePath);
-                            const refBaseName = path.basename(refFileName, '.mdc');
-                            candidatePaths.push(path.join(skillsDir, refBaseName, refFileName));
-                        }
-                        let referencedContent = null;
-                        let actualPath = referencedPath;
-                        for (const candidatePath of candidatePaths) {
-                            try {
-                                referencedContent = await fs.readFile(candidatePath, 'utf8');
-                                actualPath = candidatePath;
-                                break;
-                            }
-                            catch {
-                                // Try next candidate
-                            }
-                        }
-                        if (referencedContent === null) {
-                            warnings.push(`Cannot migrate ${skillName}: referenced file not found at ${actualPath}`);
-                        }
-                        else {
-                            // Parse the referenced file for frontmatter
-                            const { frontmatter: refFrontmatter, body: refBody } = (0, FrontmatterParser_1.parseFrontmatter)(referencedContent);
-                            // Create sibling .mdc - only keep frontmatter for alwaysApply rules
-                            let mdcContent;
-                            if (refFrontmatter?.alwaysApply === true) {
-                                // alwaysApply rules keep frontmatter (description since no SKILL.md)
-                                const mdcFrontmatterData = {
-                                    alwaysApply: true,
-                                };
-                                if (refFrontmatter.description) {
-                                    mdcFrontmatterData.description = refFrontmatter.description;
-                                }
-                                mdcContent = `---
-${yaml.dump(mdcFrontmatterData, { lineWidth: -1, noRefs: true }).trim()}
----
-
-${refBody}
-`;
-                            }
-                            else {
-                                // Regular skills: body only (description goes in SKILL.md)
-                                mdcContent = refBody;
-                            }
-                            // Update SKILL.md to point to sibling .mdc (absolute path)
-                            const newFrontmatter = {
-                                name: skillFrontmatter?.name || skillName,
-                                description: refFrontmatter?.description ||
-                                    skillFrontmatter?.description ||
-                                    `Skill: ${skillName}`,
-                            };
-                            const newSkillMd = `---
-${yaml.dump(newFrontmatter, { lineWidth: -1, noRefs: true }).trim()}
----
-
-@.claude/skills/${skillName}/${skillName}.mdc
-`;
-                            if (dryRun) {
-                                (0, constants_1.logVerboseInfo)(`DRY RUN: Would migrate ${skillName} from ${refCheck.referencePath} to sibling pattern`, verbose, dryRun);
-                            }
-                            else {
-                                await fs.writeFile(siblingMdcPath, mdcContent, 'utf8');
-                                await fs.writeFile(skillMdPath, newSkillMd, 'utf8');
-                                (0, constants_1.logVerboseInfo)(`Migrated ${skillName} from ${actualPath} to sibling pattern`, verbose, dryRun);
-                            }
-                            synced.push(skillName);
-                        }
-                    }
-                }
-                else {
-                    // Case 3: SKILL.md has full content → generate sibling .mdc, update to @reference
-                    // Generate .mdc from SKILL.md body (no frontmatter needed - description is in SKILL.md)
-                    const mdcContent = skillBody;
-                    // Update SKILL.md to @reference (absolute path)
-                    // Preserve ALL existing frontmatter (use rawFrontmatter to keep custom fields like user-invocable)
-                    // Only add defaults for missing name/description
-                    const newSkillFrontmatter = skillRawFrontmatter ? { ...skillRawFrontmatter } : {};
-                    if (!newSkillFrontmatter.name) {
-                        newSkillFrontmatter.name = skillName;
-                    }
-                    if (!newSkillFrontmatter.description) {
-                        newSkillFrontmatter.description = `Skill: ${skillName}`;
-                    }
-                    const newSkillMd = `---
-${yaml.dump(newSkillFrontmatter, { lineWidth: -1, noRefs: true }).trim()}
----
-
-@.claude/skills/${skillName}/${skillName}.mdc
-`;
-                    if (dryRun) {
-                        (0, constants_1.logVerboseInfo)(`DRY RUN: Would generate ${skillName}/${skillName}.mdc and update SKILL.md`, verbose, dryRun);
-                    }
-                    else {
-                        await fs.writeFile(siblingMdcPath, mdcContent, 'utf8');
-                        await fs.writeFile(skillMdPath, newSkillMd, 'utf8');
-                        (0, constants_1.logVerboseInfo)(`Generated ${skillName}/${skillName}.mdc and updated SKILL.md to @reference`, verbose, dryRun);
-                    }
-                    synced.push(skillName);
+        }
+        const folderEntries = await fs.readdir(skillFolderPath, {
+            withFileTypes: true,
+        });
+        const mdcEntries = folderEntries.filter((folderEntry) => folderEntry.isFile() && folderEntry.name.endsWith('.mdc'));
+        const legacySingleMdcSourcePath = skillMdContent === null && mdcEntries.length === 1
+            ? path.join(skillFolderPath, mdcEntries[0].name)
+            : null;
+        if (legacySingleMdcSourcePath) {
+            const sourceContent = await fs.readFile(legacySingleMdcSourcePath, 'utf8');
+            const parsed = (0, FrontmatterParser_1.parseFrontmatter)(sourceContent);
+            const compiledBodyResult = await inlineReferenceDirectives(parsed.body, projectRoot, legacySingleMdcSourcePath, {
+                fallbackReferenceDir: skillFolderPath,
+            });
+            const compiledContent = buildCanonicalSkillContent(skillName, parsed.rawFrontmatter, compiledBodyResult.body, {
+                sourceRelPath: toProjectRelative(projectRoot, legacySingleMdcSourcePath),
+                alwaysApply: parsed.frontmatter?.alwaysApply === true,
+            });
+            if (!dryRun) {
+                await fs.writeFile(skillMdPath, compiledContent, 'utf8');
+            }
+            changed = true;
+        }
+        else if (skillMdContent === null && mdcEntries.length > 1) {
+            warnings.push(`Canonical skill '${skillName}' has multiple legacy .mdc files and no SKILL.md`);
+        }
+        if (mdcEntries.length > 0) {
+            if (!dryRun) {
+                for (const mdcEntry of mdcEntries) {
+                    await fs.rm(path.join(skillFolderPath, mdcEntry.name), {
+                        force: true,
+                    });
                 }
             }
-            // If neither exists, skip - not a valid skill folder
+            changed = true;
         }
-        catch (err) {
-            warnings.push(`Failed to sync ${skillName}: ${err.message}`);
+        if (changed) {
+            normalized.push(skillName);
+            (0, constants_1.logVerboseInfo)(dryRun
+                ? `DRY RUN: Would normalize canonical skill '${skillName}'`
+                : `Normalized canonical skill '${skillName}'`, verbose, dryRun);
         }
     }
-    return { synced, warnings };
+    return { normalized, warnings };
+}
+// Deprecated compatibility shim. Canonical skills are now plain SKILL.md only.
+async function syncMdcToSkillMd(skillsDir, verbose, dryRun) {
+    const projectRoot = path.resolve(skillsDir, '..', '..');
+    const { normalized, warnings } = await normalizeCanonicalSkills(projectRoot, skillsDir, verbose, dryRun);
+    return { synced: normalized, warnings };
 }
 /**
- * Discovers skills in the project's skills directory (.claude/skills).
+ * Discovers skills in the project's canonical skills directory.
  * Returns discovered skills, validation warnings, and deleted empty folders.
  */
 async function discoverSkills(projectRoot, skillerDir) {
-    // Use .claude/skills
-    const skillsPath = skillerDir
-        ? path.join(skillerDir, 'skills')
-        : path.join(projectRoot, constants_1.CLAUDE_SKILLS_PATH);
+    const skillsPath = await resolveProjectSkillsDir(projectRoot, skillerDir);
     // Check if skills directory exists
     try {
         await fs.access(skillsPath);
@@ -530,10 +775,15 @@ async function copySkillsToAgent(sourceSkillsDir, targetSkillsDir, projectRoot,
         }
         taken.add(destName);
         const targetSkillPath = path.join(targetSkillsDir, destName);
+        const sourceLeafName = path.basename(skillPath);
         if (!dryRun) {
-            await copySkillDirectoryForNonClaudeAgents(skillPath, targetSkillPath, projectRoot, skillPath);
-            const sourceLeafName = path.basename(skillPath);
-            if (destName !== sourceLeafName) {
+            const symlinkSafe = destName === sourceLeafName && (await skillCanBeSymlinked(skillPath));
+            const symlinkCreated = symlinkSafe &&
+                (await createRelativeDirectorySymlink(skillPath, targetSkillPath));
+            if (!symlinkCreated) {
+                await copySkillDirectoryForNonClaudeAgents(skillPath, targetSkillPath, projectRoot, skillPath);
+            }
+            if (!symlinkCreated && destName !== sourceLeafName) {
                 await rewriteSkillMdName(path.join(targetSkillPath, constants_1.SKILL_MD_FILENAME), destName);
             }
         }
@@ -546,11 +796,11 @@ async function copySkillsToAgent(sourceSkillsDir, targetSkillsDir, projectRoot,
 }
 /**
  * Gets the paths that skills will generate, for gitignore purposes.
- * Collects paths from all agents with native skills support, excluding the source (.claude/skills).
+ * Collects paths from all agents with native skills support, excluding the canonical source.
  */
 function getSkillsGitignorePaths(projectRoot, agents) {
     const paths = [];
-    const sourceSkillsPath = path.join(projectRoot, constants_1.CLAUDE_SKILLS_PATH);
+    const sourceSkillsPath = path.join(projectRoot, constants_1.CANONICAL_SKILLS_PATH);
     for (const agent of agents) {
         if (agent.supportsNativeSkills?.() && agent.getSkillsPath) {
             const skillsPath = agent.getSkillsPath(projectRoot);
@@ -568,15 +818,16 @@ function getSkillsGitignorePaths(projectRoot, agents) {
 }
 /**
  * Propagates skills for agents that need them.
- * In the new architecture, skills are committed to .claude/skills and discovered by agents natively.
- * This function now only discovers and validates skills.
+ * Canonical skills live in .agents/skills, and local .mdc authoring lives in .agents/rules.
  */
 async function propagateSkills(projectRoot, agents, skillsEnabled, verbose, dryRun, skillerDir) {
-    async function migrateLegacyCodexSkillsDir(destinationPaths) {
+    async function migrateLegacyCodexSkillsDir(currentSourceSkillsDir, destinationPaths) {
         const universalSkillsDir = path.join(projectRoot, UNIVERSAL_AGENTS_SKILLS_PATH);
         const legacyCodexSkillsDir = path.join(projectRoot, LEGACY_CODEX_SKILLS_PATH);
-        if (!destinationPaths.has(universalSkillsDir))
+        if (currentSourceSkillsDir !== universalSkillsDir &&
+            !destinationPaths.has(universalSkillsDir)) {
             return;
+        }
         try {
             await fs.access(legacyCodexSkillsDir);
         }
@@ -615,11 +866,19 @@ async function propagateSkills(projectRoot, agents, skillsEnabled, verbose, dryR
         (0, constants_1.logVerboseInfo)('Skills support disabled', verbose, dryRun);
         return;
     }
-    // Determine skills directory - always use .claude/skills
-    const skillsDir = skillerDir
-        ? path.join(skillerDir, 'skills')
-        : path.join(projectRoot, constants_1.CLAUDE_SKILLS_PATH);
-    // Compute destinations up-front so plugin sync can run even if .claude/skills is missing.
+    if (skillerDir) {
+        const extractedResult = await extractLocalRulesFromCanonicalSkills(projectRoot, verbose, dryRun);
+        for (const warning of extractedResult.warnings) {
+            (0, constants_1.logWarn)(warning, dryRun);
+        }
+        const compileResult = await compileRulesToSkills(skillerDir, projectRoot, verbose, dryRun);
+        for (const warning of compileResult.warnings) {
+            (0, constants_1.logWarn)(warning, dryRun);
+        }
+    }
+    // Determine canonical skills directory, with legacy fallback for migration.
+    const skillsDir = await resolveProjectSkillsDir(projectRoot, skillerDir);
+    // Compute destinations up-front so legacy codex migration can de-duplicate targets.
     const destinationPaths = new Set();
     for (const agent of agents) {
         if (agent.supportsNativeSkills?.() && agent.getSkillsPath) {
@@ -630,7 +889,7 @@ async function propagateSkills(projectRoot, agents, skillsEnabled, verbose, dryR
             }
         }
     }
-    await migrateLegacyCodexSkillsDir(destinationPaths);
+    await migrateLegacyCodexSkillsDir(skillsDir, destinationPaths);
     // Check if skills directory exists
     let skillsDirExists = true;
     try {
@@ -638,15 +897,15 @@ async function propagateSkills(projectRoot, agents, skillsEnabled, verbose, dryR
     }
     catch {
         skillsDirExists = false;
-        (0, constants_1.logVerboseInfo)(`No .claude/skills directory found`, verbose, dryRun);
+        (0, constants_1.logVerboseInfo)(`No skills directory found`, verbose, dryRun);
+    }
+    const ownership = await (0, SkillOwnership_1.resolveSkillOwnership)(projectRoot);
+    for (const warning of ownership.warnings) {
+        (0, constants_1.logWarn)(warning, dryRun);
     }
     if (skillsDirExists) {
-        // Sync standalone .mdc files to SKILL.md folders before discovery
-        const syncResult = await syncMdcToSkillMd(skillsDir, verbose, dryRun);
-        if (syncResult.synced.length > 0) {
-            (0, constants_1.logVerboseInfo)(`Synced ${syncResult.synced.length} .mdc file(s) to SKILL.md`, verbose, dryRun);
-        }
-        for (const warning of syncResult.warnings) {
+        const normalizeResult = await normalizeCanonicalSkills(projectRoot, skillsDir, verbose, dryRun);
+        for (const warning of normalizeResult.warnings) {
             (0, constants_1.logWarn)(warning, dryRun);
         }
         // Discover and validate skills
@@ -660,7 +919,7 @@ async function propagateSkills(projectRoot, agents, skillsEnabled, verbose, dryR
             }
         }
         if (skills.length === 0) {
-            (0, constants_1.logVerboseInfo)('No valid skills found in .claude/skills', verbose, dryRun);
+            (0, constants_1.logVerboseInfo)('No valid skills found in project skills directory', verbose, dryRun);
         }
         else {
             (0, constants_1.logVerboseInfo)(`Discovered ${skills.length} skill(s)`, verbose, dryRun);
@@ -677,7 +936,7 @@ async function propagateSkills(projectRoot, agents, skillsEnabled, verbose, dryR
         }
     }
     // Sync project Claude commands + agents as skills into agent skills dirs.
-    // This intentionally does NOT write into the committed .claude/skills source-of-truth.
+    // This intentionally does NOT write into the canonical .agents/skills source-of-truth.
     if (destinationPaths.size > 0) {
         const { syncClaudeProjectCommandsAndAgentsToSkillsDirs } = await Promise.resolve().then(() => __importStar(require('./ClaudeProjectSync')));
         await syncClaudeProjectCommandsAndAgentsToSkillsDirs({
@@ -687,17 +946,6 @@ async function propagateSkills(projectRoot, agents, skillsEnabled, verbose, dryR
             dryRun,
         });
     }
-    // Sync Claude plugins (skills + commands converted to skills) into agent skills dirs.
-    // This intentionally does NOT write into the committed .claude/skills source-of-truth.
-    if (destinationPaths.size > 0) {
-        const { syncClaudePluginsToSkillsDirs } = await Promise.resolve().then(() => __importStar(require('./ClaudePluginSync')));
-        await syncClaudePluginsToSkillsDirs({
-            projectRoot,
-            targetSkillsDirs: [...destinationPaths],
-            verbose,
-            dryRun,
-        });
-    }
 }
 /**
  * Recursively finds all folders containing SKILL.md in a directory.