refactor: Restructure skill-lint to 6 generic validators with multi-skill support

BREAKING CHANGE: Validator names changed from 4 to 6:
- performance → size (line count, token budgets)
- NEW: references (reference file analysis, README conciseness)
- NEW: links (relative/anchor/external link validation)
- triggering → keywords (keyword-based simulation + quality scoring)
- integration → harness (real Claude CLI execution with quality metrics)
- structure (unchanged)

Features:
- Multi-skill linting: point at directory of skills to lint all
- Backward compatible: old config keys (performance/triggering/integration) still work
- Enhanced validation: 45 new rules across all validators
- Improved CLI: --size, --references, --links, --keywords, --harness flags

Config changes:
- scenarios.performance → scenarios.size
- scenarios.triggering → scenarios.keywords
- scenarios.integration → scenarios.harness
- scenarios.links: now object { enabled, checkExternal }
- Old keys automatically mapped via Zod preprocess

Tests:
- 463 tests passing (+45 from 418)
- 5 new test files
- All existing tests updated for new config shape

Author: d3xter666

plugins/ui5/skill-lint/README.md

@@ -3,7 +3,7 @@
  */
 
 import { resolve, relative, isAbsolute, join, dirname } from 'path';
-import { realpath, access, constants } from 'fs/promises';
+import { realpath, access, readdir, stat, constants } from 'fs/promises';
 import { existsSync } from 'fs';
 import { SkillLinter } from '../../core/linter.js';
 import { loadConfig, mergeWithDefaults } from '../../config/loader.js';
@@ -20,6 +20,12 @@ export interface LintOptions {
   format?: string;
   output?: string;
   structure?: boolean;
+  size?: boolean;
+  references?: boolean;
+  links?: boolean;
+  keywords?: boolean;
+  harness?: boolean;
+  // Backward compat CLI flags
   triggering?: boolean;
   performance?: boolean;
   integration?: boolean;
@@ -43,11 +49,37 @@ export async function lintCommand(
     }
 
     // Validate skill path for security (prevents path traversal attacks)
-    const resolvedPath = await validateSkillPath(skillPath);
+    const resolvedPaths = await resolveSkillPaths(skillPath);
     const config = await buildConfig(options);
     const formatter = getFormatter(config.formatters.default, config.formatters.options.colors);
     const isMachineFormat = config.formatters.default !== 'text';
 
+    if (resolvedPaths.length > 1) {
+      // Multi-skill mode
+      if (!isMachineFormat) {
+        Logger.start(`Linting ${resolvedPaths.length} skills in ${skillPath}`);
+      }
+
+      const linter = new SkillLinter(config);
+      let allPassed = true;
+
+      for (const resolvedPath of resolvedPaths) {
+        const result = await linter.lint(resolvedPath, config);
+        const output = formatter.format(result);
+        console.log(output);
+        if (!result.passed) allPassed = false;
+      }
+
+      if (options.output) {
+        Logger.document(`Multi-skill report: use --format json for combined output`);
+      }
+
+      return allPassed ? 0 : 1;
+    }
+
+    // Single-skill mode
+    const resolvedPath = resolvedPaths[0];
+
     if (!isMachineFormat) {
       Logger.start(`Linting ${resolvedPath}`);
     }
@@ -73,6 +105,58 @@ export async function lintCommand(
   }
 }
 
+/**
+ * Resolve one or more SKILL.md paths from the given input path.
+ * If the path is a directory containing multiple skill subdirectories, returns all of them.
+ * Otherwise delegates to validateSkillPath for a single path.
+ */
+async function resolveSkillPaths(skillPath: string): Promise<string[]> {
+  // SECURITY: Sanitize path first
+  let sanitized: string;
+  try {
+    sanitized = sanitizePath(skillPath);
+  } catch (error) {
+    throw new Error(`Invalid skill path: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  const workspaceRoot = await findGitRoot() || process.cwd();
+  const resolved = resolve(workspaceRoot, sanitized);
+
+  if (!existsSync(resolved)) {
+    throw new Error(`Skill path does not exist: ${skillPath}`);
+  }
+
+  // If it's a file, treat as single skill
+  const stats = await stat(resolved);
+  if (stats.isFile()) {
+    return [await validateSkillPath(skillPath)];
+  }
+
+  // If it's a directory, check for SKILL.md directly inside
+  const directSkill = join(resolved, 'SKILL.md');
+  if (existsSync(directSkill)) {
+    return [await validateSkillPath(skillPath)];
+  }
+
+  // Multi-skill mode: scan subdirectories for SKILL.md files
+  const entries = await readdir(resolved, { withFileTypes: true });
+  const skillPaths: string[] = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const subSkill = join(resolved, entry.name, 'SKILL.md');
+    if (existsSync(subSkill)) {
+      skillPaths.push(subSkill);
+    }
+  }
+
+  if (skillPaths.length === 0) {
+    throw new Error(`No SKILL.md files found in directory: ${skillPath}`);
+  }
+
+  return skillPaths;
+}
+
 /**
  * Validate skill path for security and correctness
  * Prevents path traversal attacks and ensures path points to valid SKILL.md
@@ -165,13 +249,22 @@ async function buildConfig(options: LintOptions): Promise<LintConfig> {
   // CLI flags override file config
   const overrides: Record<string, unknown> = {};
 
-  if (options.structure !== undefined || options.triggering !== undefined ||
-      options.performance !== undefined || options.integration !== undefined) {
+  const hasScenarioFlag = options.structure !== undefined || options.size !== undefined ||
+      options.references !== undefined || options.links !== undefined ||
+      options.keywords !== undefined || options.harness !== undefined ||
+      options.triggering !== undefined || options.performance !== undefined ||
+      options.integration !== undefined;
+
+  if (hasScenarioFlag) {
     overrides.scenarios = {
       structure: options.structure ?? fileConfig.scenarios.structure,
-      triggering: options.triggering ?? fileConfig.scenarios.triggering,
-      performance: options.performance ?? fileConfig.scenarios.performance,
-      integration: options.integration ?? fileConfig.scenarios.integration,
+      size: (options.size ?? options.performance) ?? fileConfig.scenarios.size,
+      references: options.references ?? fileConfig.scenarios.references,
+      links: options.links !== undefined
+        ? { enabled: options.links, checkExternal: fileConfig.scenarios.links?.checkExternal ?? false }
+        : fileConfig.scenarios.links,
+      keywords: (options.keywords ?? options.triggering) ?? fileConfig.scenarios.keywords,
+      harness: (options.harness ?? options.integration) ?? fileConfig.scenarios.harness,
     };
   }
 

plugins/ui5/skill-lint/src/cli/commands/lint.ts

@@ -24,12 +24,20 @@ export function createCLI(): Command {
     .option('-f, --format <format>', 'Output format: text, json, github-actions', 'text')
     .option('-o, --output <path>', 'Write report to file')
     .option('--structure', 'Run structure validation')
-    .option('--triggering', 'Run triggering simulation')
-    .option('--performance', 'Run performance checks')
-    .option('--integration', 'Run integration tests (requires adapter)')
+    .option('--size', 'Run size checks')
+    .option('--references', 'Run reference file analysis')
+    .option('--links', 'Run link validation')
+    .option('--keywords', 'Run keyword/triggering simulation')
+    .option('--harness', 'Run harness tests (requires adapter)')
+    // Backward compat flags
+    .option('--triggering', 'Run keyword simulation (alias for --keywords)')
+    .option('--performance', 'Run size checks (alias for --size)')
+    .option('--integration', 'Run harness tests (alias for --harness)')
     .option('--no-structure', 'Skip structure validation')
-    .option('--no-triggering', 'Skip triggering simulation')
-    .option('--no-performance', 'Skip performance checks')
+    .option('--no-size', 'Skip size checks')
+    .option('--no-references', 'Skip reference analysis')
+    .option('--no-links', 'Skip link validation')
+    .option('--no-keywords', 'Skip keyword simulation')
     .option('-v, --verbose', 'Verbose output')
     .action(async (path: string, options) => {
       const exitCode = await lintCommand(path, options);

plugins/ui5/skill-lint/src/cli/index.ts

@@ -6,24 +6,80 @@ import { z } from 'zod';
 import type { LintConfig } from '../types/index.js';
 
 export const lintConfigSchema = z.object({
-  scenarios: z.object({
-    structure: z.boolean().default(true),
-    triggering: z.boolean().default(true),
-    performance: z.boolean().default(true),
-    integration: z.boolean().default(false),
-  }).default({}),
+  scenarios: z.preprocess(
+    (val) => {
+      if (typeof val !== 'object' || val === null) return val;
+      const raw = val as Record<string, unknown>;
+      const result = { ...raw };
+      // Map old names → new before Zod applies defaults
+      if (raw.performance !== undefined && raw.size === undefined) {
+        result.size = raw.performance;
+      }
+      if (raw.triggering !== undefined && raw.keywords === undefined) {
+        result.keywords = raw.triggering;
+      }
+      if (raw.integration !== undefined && raw.harness === undefined) {
+        result.harness = raw.integration;
+      }
+      return result;
+    },
+    z.object({
+      structure: z.boolean().default(true),
+      size: z.boolean().default(true),
+      references: z.boolean().default(true),
+      links: z.preprocess(
+        (val) => {
+          if (typeof val === 'boolean') return { enabled: val };
+          if (typeof val === 'object' && val !== null) return val;
+          return { enabled: true };
+        },
+        z.object({
+          enabled: z.boolean().default(true),
+          checkExternal: z.boolean().default(false),
+        }).default({ enabled: true, checkExternal: false }),
+      ),
+      keywords: z.boolean().default(true),
+      harness: z.boolean().default(false),
+      // Keep old names passthrough for backward compat (not used after transform)
+      performance: z.boolean().optional(),
+      triggering: z.boolean().optional(),
+      integration: z.boolean().optional(),
+    }).default({}),
+  ),
 
   adapter: z.string().default('claude-code'),
 
-  thresholds: z.object({
-    performance: z.object({
-      maxLines: z.number().positive().default(700),
-      maxTokens: z.number().positive().default(4000),
+  thresholds: z.preprocess(
+    (val) => {
+      if (typeof val !== 'object' || val === null) return val;
+      const raw = val as Record<string, unknown>;
+      const result = { ...raw };
+      if (raw.performance && !raw.size) {
+        result.size = raw.performance;
+      }
+      if (raw.triggering && !raw.keywords) {
+        result.keywords = raw.triggering;
+      }
+      return result;
+    },
+    z.object({
+      size: z.object({
+        maxLines: z.number().positive().default(700),
+        maxTokens: z.number().positive().default(4000),
+      }).default({}),
+      keywords: z.object({
+        minAccuracy: z.number().min(0).max(100).default(90),
+      }).default({}),
+      // Backward compat aliases (passthrough)
+      performance: z.object({
+        maxLines: z.number().positive().default(700),
+        maxTokens: z.number().positive().default(4000),
+      }).optional(),
+      triggering: z.object({
+        minAccuracy: z.number().min(0).max(100).default(90),
+      }).optional(),
     }).default({}),
-    triggering: z.object({
-      minAccuracy: z.number().min(0).max(100).default(90),
-    }).default({}),
-  }).default({}),
+  ),
 
   testCases: z.object({
     triggering: z.string().optional(),

plugins/ui5/skill-lint/src/config/schema.ts

@@ -3,9 +3,11 @@
  */
 
 import { StructureValidator } from '../validators/structure-validator.js';
-import { PerformanceValidator } from '../validators/performance-validator.js';
-import { TriggeringValidator } from '../validators/triggering-validator.js';
-import { IntegrationValidator } from '../validators/integration-validator.js';
+import { SizeValidator } from '../validators/size-validator.js';
+import { ReferenceValidator } from '../validators/reference-validator.js';
+import { LinkValidator } from '../validators/link-validator.js';
+import { KeywordValidator } from '../validators/keyword-validator.js';
+import { HarnessValidator } from '../validators/harness-validator.js';
 import { BaseValidator } from '../validators/base-validator.js';
 import { collectResults } from './result-collector.js';
 import { loadSkill } from '../utils/file-utils.js';
@@ -20,9 +22,11 @@ export class SkillLinter {
     const validators: BaseValidator[] = [];
 
     if (config.scenarios.structure) validators.push(new StructureValidator());
-    if (config.scenarios.performance) validators.push(new PerformanceValidator());
-    if (config.scenarios.triggering) validators.push(new TriggeringValidator());
-    if (config.scenarios.integration) validators.push(new IntegrationValidator());
+    if (config.scenarios.size) validators.push(new SizeValidator());
+    if (config.scenarios.references) validators.push(new ReferenceValidator());
+    if (config.scenarios.links?.enabled) validators.push(new LinkValidator());
+    if (config.scenarios.keywords) validators.push(new KeywordValidator());
+    if (config.scenarios.harness) validators.push(new HarnessValidator());
 
     this.validators = validators;
   }

plugins/ui5/skill-lint/src/core/linter.ts

@@ -13,4 +13,12 @@ export { ClaudeCodeAdapter } from './adapters/claude-code-adapter.js';
 export { getAdapter, listAdapters } from './adapters/adapter-registry.js';
 export { createCLI } from './cli/index.js';
 
+// Validators
+export { StructureValidator } from './validators/structure-validator.js';
+export { SizeValidator } from './validators/size-validator.js';
+export { ReferenceValidator } from './validators/reference-validator.js';
+export { LinkValidator } from './validators/link-validator.js';
+export { KeywordValidator } from './validators/keyword-validator.js';
+export { HarnessValidator } from './validators/harness-validator.js';
+
 export type * from './types/index.js';

plugins/ui5/skill-lint/src/index.ts

@@ -147,17 +147,34 @@ export type ProgressCallback = (event: ProgressEvent) => void;
 export interface LintConfig {
   readonly scenarios: {
     readonly structure: boolean;
-    readonly triggering: boolean;
-    readonly performance: boolean;
-    readonly integration: boolean;
+    readonly size: boolean;
+    readonly references: boolean;
+    readonly links: {
+      readonly enabled: boolean;
+      readonly checkExternal: boolean;
+    };
+    readonly keywords: boolean;
+    readonly harness: boolean;
+    // Backward compat (optional, mapped by Zod transform)
+    readonly performance?: boolean;
+    readonly triggering?: boolean;
+    readonly integration?: boolean;
   };
   readonly adapter: string;
   readonly thresholds: {
-    readonly performance: {
+    readonly size: {
+      readonly maxLines: number;
+      readonly maxTokens: number;
+    };
+    readonly keywords: {
+      readonly minAccuracy: number;
+    };
+    // Backward compat
+    readonly performance?: {
       readonly maxLines: number;
       readonly maxTokens: number;
     };
-    readonly triggering: {
+    readonly triggering?: {
       readonly minAccuracy: number;
     };
   };