refactor(errors): use dedicated MANIFEST_VALIDATION_ERROR code for skills.json validation

- Add new error code EMANIFESTVAL for manifest validation errors
- Use ManifestError instead of SkillError for validation failures
- Add helpful error message pointing to JSON Schema reference

Author: SoonIter

packages/skills-package-manager/src/config/readSkillsManifest.ts

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises'
 import path from 'node:path'
-import { convertNodeError, ErrorCode, ParseError, SkillError } from '../errors'
+import { convertNodeError, ErrorCode, ManifestError, ParseError } from '../errors'
 import { skillsManifestSchema } from './schema'
 import type { SkillsManifest } from './types'
 
@@ -28,9 +28,9 @@ export async function readSkillsManifest(rootDir: string): Promise<SkillsManifes
       const issues = result.error.issues
         .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
         .join('\n  - ')
-      throw new SkillError({
-        code: ErrorCode.VALIDATION_ERROR,
-        skillName: 'manifest',
+      throw new ManifestError({
+        code: ErrorCode.MANIFEST_VALIDATION_ERROR,
+        filePath,
         message: `Invalid skills.json:\n  - ${issues}`,
       })
     }
@@ -40,7 +40,7 @@ export async function readSkillsManifest(rootDir: string): Promise<SkillsManifes
     if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
       return null
     }
-    if (error instanceof ParseError || error instanceof SkillError) {
+    if (error instanceof ParseError || error instanceof ManifestError) {
       throw error
     }
     throw convertNodeError(error as NodeJS.ErrnoException, { operation: 'read', path: filePath })

packages/skills-package-manager/src/errors/codes.ts

@@ -27,6 +27,7 @@ export enum ErrorCode {
   LOCKFILE_NOT_FOUND = 'ELOCKFILE',
   LOCKFILE_OUTDATED = 'ELOCKOUTDATED',
   MANIFEST_EXISTS = 'EMANIFESTEXISTS',
+  MANIFEST_VALIDATION_ERROR = 'EMANIFESTVAL',
 
   // Network/Remote errors (5xx)
   NETWORK_ERROR = 'ENETWORK',

packages/skills-package-manager/src/errors/index.ts

@@ -124,6 +124,9 @@ export function formatErrorForDisplay(error: unknown): string {
       if (error.code === ErrorCode.LOCKFILE_OUTDATED) {
         output += `\n\nThe lockfile is out of sync with skills.json.`
         output += `\nRun "spm install" to update the lockfile.`
+      } else if (error.code === ErrorCode.MANIFEST_VALIDATION_ERROR) {
+        output += `\n\nPlease fix the validation errors in "${error.filePath}".`
+        output += `\nRefer to the JSON Schema at: https://unpkg.com/skills-package-manager@latest/skills.schema.json`
       }
     }
 

packages/skills-package-manager/src/errors/types.ts

@@ -114,6 +114,7 @@ export class ManifestError extends SpmError {
       | ErrorCode.LOCKFILE_NOT_FOUND
       | ErrorCode.LOCKFILE_OUTDATED
       | ErrorCode.MANIFEST_EXISTS
+      | ErrorCode.MANIFEST_VALIDATION_ERROR
     filePath: string
     message?: string
     cause?: Error
@@ -123,6 +124,7 @@ export class ManifestError extends SpmError {
       [ErrorCode.LOCKFILE_NOT_FOUND]: `Lockfile not found: ${options.filePath}`,
       [ErrorCode.LOCKFILE_OUTDATED]: `Lockfile is out of date: ${options.filePath}`,
       [ErrorCode.MANIFEST_EXISTS]: `Manifest already exists: ${options.filePath}`,
+      [ErrorCode.MANIFEST_VALIDATION_ERROR]: `Invalid skills.json: ${options.filePath}`,
     }
     const message =
       options.message ?? defaultMessages[options.code] ?? `Manifest error: ${options.filePath}`