fix: check shipped skills before doc resolution fallback (#48)

Author: harlan-zw

src/commands/sync-parallel.ts

@@ -401,7 +401,7 @@ async function syncBaseSkill(
   const localDeps = await readLocalDependencies(cwd).catch(() => [])
   const localVersion = localDeps.find(d => d.name === packageName)?.version
 
-  const { package: resolvedPkg, attempts } = await resolvePackageDocsWithAttempts(requestedTag ? packageSpec : packageName, {
+  const { package: resolvedPkg, attempts, registryVersion } = await resolvePackageDocsWithAttempts(requestedTag ? packageSpec : packageName, {
     version: localVersion,
     cwd,
     onProgress: step => update(packageName, 'resolving', RESOLVE_STEP_LABELS[step]),
@@ -414,6 +414,19 @@ async function syncBaseSkill(
   }
 
   if (!resolved) {
+    // Even without docs, the package may ship its own skills (skills-npm convention)
+    const shippedVersion = localVersion || registryVersion || 'latest'
+    const earlyShipped = handleShippedSkills(packageName, shippedVersion, cwd, config.agent, config.global)
+    if (earlyShipped) {
+      const shared = !config.global && getSharedSkillsDir(cwd)
+      if (shared) {
+        for (const shipped of earlyShipped.shipped)
+          linkSkillToAgents(shipped.skillName, shared, cwd, config.agent)
+      }
+      update(packageName, 'done', 'Published SKILL.md', getVersionKey(shippedVersion))
+      return 'shipped'
+    }
+
     const npmAttempt = attempts.find(a => a.source === 'npm')
     let reason: string
     if (npmAttempt?.status === 'not-found') {

src/commands/sync.ts

@@ -290,6 +290,20 @@ async function syncSinglePackage(packageSpec: string, config: SyncConfig): Promi
   }
 
   if (!resolved) {
+    // Even without docs, the package may ship its own skills (skills-npm convention)
+    const shippedVersion = localVersion || resolveResult.registryVersion || 'latest'
+    const earlyShipped = handleShippedSkills(packageName, shippedVersion, cwd, config.agent, config.global)
+    if (earlyShipped) {
+      const shared = !config.global && getSharedSkillsDir(cwd)
+      for (const shipped of earlyShipped.shipped) {
+        if (shared)
+          linkSkillToAgents(shipped.skillName, shared, cwd, config.agent)
+        p.log.success(`Using published SKILL.md: ${shipped.skillName} → ${relative(cwd, shipped.skillDir)}`)
+      }
+      spin.stop(`Using published SKILL.md(s) from ${packageName}`)
+      return
+    }
+
     // Search npm for alternatives before giving up
     spin.message(`Searching npm for "${packageName}"...`)
     const suggestions = await searchNpmPackages(packageName)

src/sources/npm.ts

@@ -375,10 +375,10 @@ export async function resolvePackageDocsWithAttempts(packageName: string, option
 
   // Must have at least one source
   if (!result.docsUrl && !result.llmsUrl && !result.readmeUrl && !result.gitDocsUrl) {
-    return { package: null, attempts }
+    return { package: null, attempts, registryVersion: pkg.version }
   }
 
-  return { package: result, attempts }
+  return { package: result, attempts, registryVersion: pkg.version }
 }
 
 /**

src/sources/types.ts

@@ -74,4 +74,6 @@ export interface ResolveAttempt {
 export interface ResolveResult {
   package: ResolvedPackage | null
   attempts: ResolveAttempt[]
+  /** npm registry version, available even when doc resolution fails */
+  registryVersion?: string
 }