@botdocs/cli 0.10.2 → 0.11.0

package/dist/commands/sync.js

@@ -3,14 +3,15 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { render } from 'ink';
-import { ApiError, apiFetch, fetchRawContent } from '../lib/api.js';
+import { ApiError, apiFetch, fetchRawContent, friendlyApiErrorDetail } from '../lib/api.js';
 import { loadLockfile, fingerprintFile, fingerprintContent, upsertInstall, } from '../lib/lockfile.js';
 import { renderDiff, hasChanges } from '../lib/diff.js';
 import { promptConflict, confirmOverwrite, promptCleanUpdate } from '../lib/prompts.js';
 import { syncLibrary } from '../lib/library-sync.js';
 import { detectDestination } from '../lib/auto-detect.js';
-import { backupDestination, backupFile, isLockfileOwnedAndUnchanged } from '../lib/backup.js';
+import { backupDestination, backupFile, isLockfileOwnedAndUnchanged, } from '../lib/backup.js';
 import { SyncApp } from './views/sync-app.js';
+import { parseRef } from '../lib/ref.js';
 /** Backup the existing content at `dest` before sync overwrites it. Skipped
  * entirely if `--no-backup` is set or the file is "ours and unchanged" per
  * the lockfile. Under `--dry-run`, prints the would-be backup path but does
@@ -49,13 +50,54 @@ async function syncSkill(entry, manifest, deps) {
     let updatedCount = 0;
     let skippedCount = 0;
     let conflicted = false;
+    // Track which file paths actually changed during this sync — surfaced in
+    // the live view's "details" so the user can see WHAT updated, not just
+    // that something did. Naming sources via `installedFile.src` (the
+    // upstream-relative path) is consistent across destinations.
+    const updatedFiles = [];
+    // Track which file paths were explicitly skipped on conflict so the
+    // lockfile entry can record them. Distinct from `updatedFiles` so callers
+    // can render "updated: …" and "skipped: …" separately.
+    const skippedFiles = [];
     const newFiles = [];
     for (const installedFile of entry.files) {
         const upstream = manifest.files.find((f) => f.filename === installedFile.src);
         if (!upstream) {
-            // Upstream removed this file — delete the local copy and drop the lockfile entry.
-            if (fs.existsSync(installedFile.dest))
-                fs.unlinkSync(installedFile.dest);
+            // Upstream removed this file. If the local copy is lockfile-owned-and-
+            // unchanged, quietly unlink — we wrote those bytes and the user hasn't
+            // touched them, so there's nothing to preserve. If the file has been
+            // locally edited (or is untracked at this path), back it up first so
+            // the README's "never silently clobber" promise holds for deletions
+            // too. --no-backup respects the user's opt-out.
+            if (fs.existsSync(installedFile.dest)) {
+                const ownedAndClean = isLockfileOwnedAndUnchanged(installedFile.dest);
+                if (!ownedAndClean && !options.noBackup) {
+                    if (options.dryRun) {
+                        if (!silent && !options.json) {
+                            const projectDir = process.cwd();
+                            const wouldDest = backupDestination(installedFile.dest, projectDir);
+                            const relSrc = path.relative(projectDir, installedFile.dest);
+                            const relDest = path.relative(projectDir, wouldDest);
+                            console.log(`  ⚠ Would back up ${relSrc} → ${relDest} (upstream removed)`);
+                        }
+                    }
+                    else {
+                        const result = backupFile(installedFile.dest, process.cwd());
+                        if (!silent && !options.json) {
+                            if (result.ok) {
+                                const relSrc = path.relative(process.cwd(), installedFile.dest);
+                                const relDest = path.relative(process.cwd(), result.dest);
+                                console.log(`  ⚠ ${relSrc}: backed up to ${relDest} before removing (had local edits)`);
+                            }
+                            else {
+                                console.log(`  ⚠ Could not back up ${installedFile.dest}: ${result.error} — proceeding with removal.`);
+                            }
+                        }
+                    }
+                }
+                if (!options.dryRun)
+                    fs.unlinkSync(installedFile.dest);
+            }
             if (!silent) {
                 console.log(`  ⌀ ${entry.ref}: removed ${installedFile.src} (no longer in upstream)`);
             }
@@ -69,6 +111,7 @@ async function syncSkill(entry, manifest, deps) {
             const fp = fingerprintFile(installedFile.dest);
             newFiles.push({ ...installedFile, fingerprint: fp });
             updatedCount++;
+            updatedFiles.push(installedFile.src);
             continue;
         }
         const localContent = fs.readFileSync(installedFile.dest, 'utf-8');
@@ -109,10 +152,12 @@ async function syncSkill(entry, manifest, deps) {
                 const fp = options.dryRun ? installedFile.fingerprint : fingerprintFile(installedFile.dest);
                 newFiles.push({ ...installedFile, fingerprint: fp });
                 updatedCount++;
+                updatedFiles.push(installedFile.src);
             }
             else {
                 newFiles.push(installedFile);
                 skippedCount++;
+                skippedFiles.push(installedFile.src);
             }
             continue;
         }
@@ -128,6 +173,7 @@ async function syncSkill(entry, manifest, deps) {
         if (choice === 'skip' || choice === 'keep') {
             newFiles.push(installedFile);
             skippedCount++;
+            skippedFiles.push(installedFile.src);
             continue;
         }
         // 'overwrite': the user accepted. Backup-on-overwrite always runs unless
@@ -139,23 +185,50 @@ async function syncSkill(entry, manifest, deps) {
         const fp = options.dryRun ? installedFile.fingerprint : fingerprintFile(installedFile.dest);
         newFiles.push({ ...installedFile, fingerprint: fp });
         updatedCount++;
+        updatedFiles.push(installedFile.src);
     }
     if (!options.dryRun) {
-        // Only bump the lockfile version when no files were skipped — otherwise
-        // the local copy still represents the old version on at least one file.
-        const canBumpVersion = skippedCount === 0;
+        // Always bump the lockfile to the upstream version when anything moved.
+        // Previously we held the entry's version at the old value whenever any
+        // file was skipped — which caused the same files to be flagged on every
+        // subsequent sync (a confusing "still updated" loop). Instead, bump the
+        // version and record a `partial: true` marker with the list of skipped
+        // file `src`s. The next sync sees the bumped version, only re-resolves
+        // files whose upstream content still differs (clean files won't), and
+        // surfaces the partial state in the summary line.
         const filesShrunk = newFiles.length < entry.files.length;
-        const shouldWrite = updatedCount > 0 || filesShrunk || (canBumpVersion && manifest.version !== entry.version);
+        const versionChanged = manifest.version !== entry.version;
+        const partialStateChanged = Boolean(entry.partial) !== (skippedCount > 0) ||
+            (entry.skippedFiles ?? []).slice().sort().join('|') !== skippedFiles.slice().sort().join('|');
+        const shouldWrite = updatedCount > 0 || filesShrunk || versionChanged || partialStateChanged;
         if (shouldWrite) {
-            upsertInstall({
+            const next = {
                 ...entry,
-                version: canBumpVersion ? manifest.version : entry.version,
+                version: manifest.version,
                 files: newFiles,
                 installedAt: new Date().toISOString(),
-            });
+            };
+            if (skippedCount > 0) {
+                next.partial = true;
+                next.skippedFiles = skippedFiles;
+            }
+            else {
+                // Clean run — strip the markers so a previously-partial entry
+                // can be displayed as up-to-date again. Setting to undefined
+                // keeps the lockfile JSON small (omitted fields are ignored).
+                delete next.partial;
+                delete next.skippedFiles;
+            }
+            upsertInstall(next);
         }
     }
-    return { updated: updatedCount > 0, skipped: skippedCount, conflicted };
+    return {
+        updated: updatedCount > 0,
+        skipped: skippedCount,
+        conflicted,
+        updatedFiles,
+        skippedFiles,
+    };
 }
 function refToPath(ref) {
     const cleaned = ref.startsWith('@') ? ref.slice(1) : ref;
@@ -200,6 +273,12 @@ async function installTeamSkill(teamSlug, skill, options, silent) {
     }
     catch (err) {
         if (err instanceof ApiError) {
+            // 410 = team-pinned skill was removed by its author. Surface the
+            // uninstall hint so the user knows why a previously-installable
+            // team skill won't sync anymore.
+            if (err.status === 410) {
+                console.error(`\n  ⌀ ${ref}: removed by author — run \`botdocs uninstall ${ref}\` to clean up local files.\n`);
+            }
             return { ref, status: 'skipped' };
         }
         throw err;
@@ -249,6 +328,42 @@ async function installTeamSkill(teamSlug, skill, options, silent) {
     });
     return { ref, status: existing ? 'updated' : 'installed' };
 }
+/** Reconcile a single bundle entry against its upstream manifest. The contained
+ * skills are NOT installed here (the personal-sync loop handles those via
+ * their own top-level lockfile entries); we only diff the bundle's recorded
+ * composition + version against upstream and update the bundle row. */
+async function syncBundle(entry, manifest, options) {
+    const upstreamRefs = manifest.skills.map((s) => `@${s.ref.username}/${s.ref.slug}`);
+    const upstreamSet = new Set(upstreamRefs);
+    const localSet = new Set(entry.skills ?? []);
+    const added = upstreamRefs.filter((r) => !localSet.has(r));
+    const removed = (entry.skills ?? []).filter((r) => !upstreamSet.has(r));
+    const compositionChanged = added.length > 0 || removed.length > 0;
+    const versionChanged = entry.version !== manifest.version;
+    if (!compositionChanged && !versionChanged) {
+        return { status: 'up-to-date', changed: false };
+    }
+    // Build a human-readable details string. Keep the form predictable for
+    // test assertions: "added X, Y" / "removed X" / version-delta when only
+    // the version moved. Combine forms with " (...)" wrapping.
+    const parts = [];
+    if (versionChanged)
+        parts.push(`${entry.version} → ${manifest.version}`);
+    if (added.length > 0)
+        parts.push(`added ${added.join(', ')}`);
+    if (removed.length > 0)
+        parts.push(`removed ${removed.join(', ')}`);
+    const details = parts.join(', ');
+    if (!options.dryRun) {
+        upsertInstall({
+            ...entry,
+            version: manifest.version,
+            skills: upstreamRefs,
+            installedAt: new Date().toISOString(),
+        });
+    }
+    return { status: 'updated', details, changed: true };
+}
 /** The core sync work, decoupled from presentation. Takes a dispatch + awaiter
  * pair so the Ink view and the plain-text path can share one loop. The function
  * is structured so the live view can flicker rows through their states in real
@@ -257,19 +372,11 @@ async function runSyncCore(rawRef, targets, options, deps) {
     const { dispatch, awaitConflictChoice, silent } = deps;
     const summary = [];
     for (const entry of targets) {
-        if (entry.type !== 'SKILL')
-            continue;
         dispatch({ type: 'CHECKING', ref: entry.ref });
         const { username, slug } = refToPath(entry.ref);
         let manifest;
         try {
-            const resp = await apiFetch(`/api/skills/${username}/${slug}/manifest`);
-            if (resp.type !== 'SKILL') {
-                // Bundles inside the sync flow are intentionally skipped — handled at
-                // install time. Mirror the existing behavior: silently continue.
-                continue;
-            }
-            manifest = resp;
+            manifest = await apiFetch(`/api/skills/${username}/${slug}/manifest`);
         }
         catch (err) {
             if (err instanceof ApiError) {
@@ -282,33 +389,111 @@ async function runSyncCore(rawRef, targets, options, deps) {
                     dispatch({ type: 'ERROR', ref: entry.ref, details: 'not authenticated' });
                     process.exit(1);
                 }
+                // 410 Gone = author soft-deleted the skill upstream. We get a
+                // structured body from the manifest route ({error, code: 'GONE',
+                // hint}). Surface the uninstall hint instead of "api error 410" so
+                // users know how to recover their machine.
+                if (err.status === 410) {
+                    console.error(`\n  ⌀ ${entry.ref}: removed by author — run \`botdocs uninstall ${entry.ref}\` to clean up local files.\n`);
+                    summary.push({ ref: entry.ref, status: 'skipped' });
+                    dispatch({ type: 'ERROR', ref: entry.ref, details: 'removed by author' });
+                    continue;
+                }
+                // Other 4xx/5xx — render a friendly one-liner per status class so
+                // users see "permission denied" / "rate-limited" instead of the bare
+                // "api error 403" string. Keep the wording short — it lands in the
+                // ERROR row's details column where horizontal space is tight.
+                // Passing the ref lets the helper emit `botdocs uninstall <ref>` for
+                // 404s — mirrors the 410 hint above.
+                const detail = friendlyApiErrorDetail(err, entry.ref);
                 summary.push({ ref: entry.ref, status: 'skipped' });
-                dispatch({ type: 'ERROR', ref: entry.ref, details: `api error ${err.status}` });
+                dispatch({ type: 'ERROR', ref: entry.ref, details: detail });
                 continue;
             }
             throw err;
         }
-        const { updated, skipped } = await syncSkill(entry, manifest, {
+        // Bundle entry: reconcile composition + version against upstream. Contained
+        // skills sync via their own top-level lockfile entries, so we only update
+        // the bundle row here. A bundle whose lockfile says SKILL but upstream
+        // returned BUNDLE (or vice versa) is dropped — that's a republish-as-
+        // different-type situation the user has to resolve via uninstall/install.
+        if (entry.type === 'BUNDLE') {
+            if (manifest.type !== 'BUNDLE') {
+                // Upstream changed types — surface as skipped, don't try to apply.
+                summary.push({
+                    ref: entry.ref,
+                    status: 'skipped',
+                    details: 'upstream is no longer a bundle — uninstall and reinstall',
+                });
+                dispatch({ type: 'SKIPPED', ref: entry.ref, details: 'type changed upstream' });
+                continue;
+            }
+            const bundleResult = await syncBundle(entry, manifest, options);
+            summary.push({ ref: entry.ref, status: bundleResult.status, details: bundleResult.details });
+            if (bundleResult.status === 'updated') {
+                dispatch({ type: 'UPDATED', ref: entry.ref, details: bundleResult.details ?? 'updated' });
+            }
+            else {
+                dispatch({ type: 'UP_TO_DATE', ref: entry.ref });
+            }
+            continue;
+        }
+        // Skill entry: server may have changed it to a bundle (rare, only via
+        // unpublish-and-reupload). Treat as skipped, same recovery as above.
+        if (manifest.type !== 'SKILL') {
+            summary.push({
+                ref: entry.ref,
+                status: 'skipped',
+                details: 'upstream is now a bundle — uninstall and reinstall',
+            });
+            dispatch({ type: 'SKIPPED', ref: entry.ref, details: 'type changed upstream' });
+            continue;
+        }
+        const { updated, skipped, updatedFiles, skippedFiles } = await syncSkill(entry, manifest, {
             options,
             awaitConflictChoice,
             silent,
         });
         const status = updated ? 'updated' : skipped > 0 ? 'skipped' : 'up-to-date';
-        summary.push({ ref: entry.ref, status });
         if (status === 'updated') {
-            dispatch({
-                type: 'UPDATED',
-                ref: entry.ref,
-                details: entry.version !== manifest.version
-                    ? `${entry.version} → ${manifest.version}`
-                    : 'updated',
-            });
+            // Detail prioritization: a version bump is the headline info — show
+            // the delta. When content changed but the upstream version didn't
+            // (rare, but happens for republishes), surface the file list so the
+            // user can see WHAT moved. Cap at 3 explicit filenames before
+            // collapsing to a count to keep the line readable. When `partial`
+            // (some files updated, others skipped on conflict), append a suffix
+            // so the user sees the version bumped AND that conflicts remain.
+            let details;
+            if (entry.version !== manifest.version) {
+                details = `${entry.version} → ${manifest.version}`;
+            }
+            else if (updatedFiles.length > 0 && updatedFiles.length <= 3) {
+                details = `updated: ${updatedFiles.join(', ')}`;
+            }
+            else if (updatedFiles.length > 0) {
+                details = `${updatedFiles.length} file(s) updated`;
+            }
+            else {
+                details = 'updated';
+            }
+            if (skipped > 0) {
+                details += ` (${skipped} file${skipped === 1 ? '' : 's'} skipped — conflict)`;
+            }
+            summary.push({ ref: entry.ref, status, details });
+            dispatch({ type: 'UPDATED', ref: entry.ref, details });
         }
         else if (status === 'up-to-date') {
+            summary.push({ ref: entry.ref, status });
             dispatch({ type: 'UP_TO_DATE', ref: entry.ref });
         }
         else {
-            dispatch({ type: 'SKIPPED', ref: entry.ref, details: 'changes skipped' });
+            // Pure-skipped: no files moved, ≥ 1 conflict. Surface the same
+            // shape so the user can see how many were left alone.
+            const details = skippedFiles.length > 0 && skippedFiles.length <= 3
+                ? `${skippedFiles.length} file${skippedFiles.length === 1 ? '' : 's'} skipped — conflict`
+                : 'changes skipped';
+            summary.push({ ref: entry.ref, status, details });
+            dispatch({ type: 'SKIPPED', ref: entry.ref, details });
         }
     }
     // After per-target sync, also pull team-pinned skills (unless --ref-specific).
@@ -372,10 +557,27 @@ function plainAwaitConflictChoice(ref, file) {
     })();
 }
 export async function sync(rawRef, options) {
+    // Validate the ref shape when one was passed. Without this, a typo like
+    // `botdocs sync foo` would silently fall through to "nothing installed to
+    // sync" (the lockfile filter finds no match), which masks the actual
+    // mistake. Validating up front gives the user the same clean ✗ line that
+    // install/uninstall use for malformed refs.
+    if (rawRef) {
+        try {
+            parseRef(rawRef);
+        }
+        catch {
+            console.error(`\n  ✗ Invalid ref: ${rawRef} — expected @user/slug (e.g. @yourname/my-skill)\n`);
+            process.exit(1);
+        }
+    }
     const lf = loadLockfile();
+    // Pre-P3 this filtered to SKILL only — bundle composition was never
+    // reconciled. Now both skill and bundle entries flow through runSyncCore;
+    // the loop branches by type to call syncSkill vs syncBundle.
     const targets = rawRef
         ? lf.installs.filter((i) => i.ref === rawRef)
-        : lf.installs.filter((i) => i.type === 'SKILL');
+        : lf.installs;
     const useInk = !options.noInk && Boolean(process.stdout.isTTY) && !options.json;
     if (targets.length === 0 && !rawRef) {
         // Even with nothing installed, pull team-pinned skills.
@@ -405,7 +607,11 @@ export async function sync(rawRef, options) {
         return;
     }
     if (targets.length === 0) {
-        console.log('\n  nothing installed to sync\n');
+        // rawRef was provided but no lockfile entry matches it — distinguish
+        // from the no-arg case so the user sees the actual problem ("you asked
+        // to sync something you don't have installed") instead of the generic
+        // "nothing installed".
+        console.log(`\n  ${rawRef} isn't installed. Run \`botdocs list\` to see what is.\n`);
         await syncLibrary();
         return;
     }
@@ -451,12 +657,18 @@ export async function sync(rawRef, options) {
     });
     console.log('');
     for (const s of summary) {
-        if (s.status === 'up-to-date')
+        if (s.status === 'up-to-date') {
             console.log(`  ✓ ${s.ref}: up to date`);
-        else if (s.status === 'updated')
-            console.log(`  ✓ ${s.ref}: updated`);
-        else
-            console.log(`  ⌀ ${s.ref}: changes skipped`);
+        }
+        else if (s.status === 'updated') {
+            // Surface the same details string the Ink view shows — either the
+            // version delta or the per-file change list — so users on the plain
+            // path can also see WHAT updated.
+            console.log(`  ✓ ${s.ref}: ${s.details ?? 'updated'}`);
+        }
+        else {
+            console.log(`  ⌀ ${s.ref}: ${s.details ?? 'changes skipped'}`);
+        }
     }
     for (const r of teamResults) {
         if (r.status === 'installed')

package/dist/commands/uninstall.js

@@ -1,7 +1,19 @@
 import fs from 'node:fs';
 import { loadLockfile, removeInstall } from '../lib/lockfile.js';
 import { syncLibrary } from '../lib/library-sync.js';
+import { parseRef } from '../lib/ref.js';
 export async function uninstall(rawRef, options) {
+    // Validate ref shape up front so a typo (`botdocs uninstall foo`) prints a
+    // friendly error rather than slipping through to the lockfile lookup and
+    // bottoming out at the generic "Not installed" message — which would be
+    // misleading because the ref is malformed, not just missing.
+    try {
+        parseRef(rawRef);
+    }
+    catch {
+        console.error(`\n  ✗ Invalid ref: ${rawRef} — expected @user/slug (e.g. @yourname/my-skill)\n`);
+        process.exit(1);
+    }
     const lf = loadLockfile();
     const entry = lf.installs.find((i) => i.ref === rawRef);
     if (!entry) {

package/dist/commands/validate.js

@@ -1,6 +1,33 @@
 import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
-import { join, extname } from 'path';
+import { join, relative, sep } from 'path';
 import { parseManifest, ManifestError } from '../lib/manifest.js';
+import { stripFrontmatter } from '../lib/convert.js';
+import { PER_FILE_BYTE_CAP, PER_SKILL_BYTE_CAP, PER_SKILL_FILE_CAP, formatKB, } from '../lib/skill-caps.js';
+/** Recursively collect markdown files under `dir`, returning POSIX-style paths
+ * relative to `dir`. Skips dotfiles/dotdirs (same rule publish.ts uses). */
+function collectMarkdownFiles(dir) {
+    const out = [];
+    walk(dir, dir, out);
+    return out;
+}
+function walk(rootDir, currentDir, out) {
+    for (const entry of readdirSync(currentDir)) {
+        if (entry.startsWith('.'))
+            continue;
+        const fullPath = join(currentDir, entry);
+        const stat = statSync(fullPath);
+        if (stat.isDirectory()) {
+            walk(rootDir, fullPath, out);
+            continue;
+        }
+        if (!stat.isFile())
+            continue;
+        if (!entry.endsWith('.md') && !entry.endsWith('.markdown'))
+            continue;
+        // POSIX-style relative path so cross-platform output is consistent.
+        out.push(relative(rootDir, fullPath).split(sep).join('/'));
+    }
+}
 export async function validate(source, options) {
     const errors = [];
     const stat = statSync(source, { throwIfNoEntry: false });
@@ -12,13 +39,14 @@ export async function validate(source, options) {
     let baseDir;
     if (stat.isDirectory()) {
         baseDir = source;
-        files = readdirSync(source).filter((f) => (extname(f) === '.md' || extname(f) === '.markdown') && statSync(join(source, f)).isFile());
+        // Recurse so canonical layouts (`claude/SKILL.md`,
+        // `claude-code/commands/<slug>.md`) and other nested skill structures
+        // count. Top-level-only would miss the canonical scaffold and report
+        // "No markdown files found" on a freshly-initialized skill.
+        files = collectMarkdownFiles(source);
         if (files.length === 0) {
             errors.push({ file: source, message: 'No markdown files found', severity: 'error' });
         }
-        if (!files.includes('index.md')) {
-            errors.push({ file: 'index.md', message: 'Missing index.md (required entry point)', severity: 'error' });
-        }
         if (existsSync(join(source, 'botdocs.json'))) {
             let raw;
             try {
@@ -32,7 +60,11 @@ export async function validate(source, options) {
                 try {
                     const parsed = parseManifest(raw);
                     if (!parsed.description) {
-                        errors.push({ file: 'botdocs.json', message: 'Missing description', severity: 'warning' });
+                        // Upgraded from warning → error so authors hit this at
+                        // `validate` time instead of being surprised by a hard
+                        // error from `publish` later. Publish requires a
+                        // description; validate must mirror that contract.
+                        errors.push({ file: 'botdocs.json', message: 'Missing description', severity: 'error' });
                     }
                 }
                 catch (err) {
@@ -53,18 +85,60 @@ export async function validate(source, options) {
         baseDir = '.';
         files = [source];
     }
+    // Enforce server-side caps locally so authors hit "your skill is too big"
+    // at `validate` time instead of getting a 413 back from publish. Cap
+    // constants live in lib/skill-caps.ts and MUST stay in sync with
+    // apps/web/src/lib/skill-caps.ts.
+    let totalBytes = 0;
     for (const file of files) {
         const filePath = stat.isDirectory() ? join(baseDir, file) : file;
         const content = readFileSync(filePath, 'utf-8');
+        const fileBytes = Buffer.byteLength(content, 'utf-8');
+        totalBytes += fileBytes;
+        if (fileBytes > PER_FILE_BYTE_CAP) {
+            errors.push({
+                file,
+                message: `File is ${formatKB(fileBytes)} (cap: ${formatKB(PER_FILE_BYTE_CAP)} per file)`,
+                severity: 'error',
+            });
+        }
         if (content.trim().length === 0) {
             errors.push({ file, message: 'File is empty', severity: 'error' });
             continue;
         }
+        // Strip YAML frontmatter before measuring body. A SKILL.md with a 200-
+        // char frontmatter block and nothing under it would otherwise pass
+        // length checks while shipping no actual content. Catching it here
+        // turns a silent registry pollution into a friendly local error.
+        const body = stripFrontmatter(content).trim();
+        if (body.length <= 100) {
+            errors.push({
+                file,
+                message: 'Skill body is empty after frontmatter — add content under the frontmatter.',
+                severity: 'error',
+            });
+            continue;
+        }
         if (!content.match(/^#\s+/m)) {
             errors.push({ file, message: 'No markdown heading found', severity: 'warning' });
         }
-        if (content.length < 100) {
-            errors.push({ file, message: 'Content is very short (< 100 chars)', severity: 'warning' });
+    }
+    // Aggregate caps: total skill size + file count. Only meaningful in
+    // directory mode — a single-file invocation is checked file-by-file above.
+    if (stat.isDirectory()) {
+        if (files.length > PER_SKILL_FILE_CAP) {
+            errors.push({
+                file: source,
+                message: `Skill has ${files.length} files (cap: ${PER_SKILL_FILE_CAP} per skill)`,
+                severity: 'error',
+            });
+        }
+        if (totalBytes > PER_SKILL_BYTE_CAP) {
+            errors.push({
+                file: source,
+                message: `Skill total size is ${formatKB(totalBytes)} (cap: ${formatKB(PER_SKILL_BYTE_CAP)} per skill)`,
+                severity: 'error',
+            });
         }
     }
     outputResults(errors, options.json);