@ai-plugin-marketplace/core 0.1.0

package/dist/targets/kiro/validate.js

@@ -0,0 +1,232 @@
+/**
+ * Per-target validators for the Kiro target.
+ *
+ * Responsibilities (v0.1.0):
+ *   1. POWER.md frontmatter — parse YAML and validate against
+ *      `kiroPowerMdFrontmatterSchema`. Missing block or missing required fields
+ *      → hard `schema-invalid`.
+ *   2. POWER.md name-consistency — frontmatter `name` must match
+ *      `path.basename(pluginDir)` → hard `name-consistency`.
+ *   3. mcp.json schema — parse JSON and validate against `kiroMcpConfigSchema`
+ *      → hard `schema-invalid`.
+ *   4. Agent tool-name warnings — for each `.md` under `agents/` (one level),
+ *      each tool not in `CLAUDE_TO_KIRO_TOOLS` → soft `schema-invalid`.
+ *
+ * What NOT validated here:
+ *   - `.kiro/agents/<name>.json` (generated output — validated at bundle time)
+ *   - Envelope adherence, marketplace registration, cross-target consistency
+ *   - Shared agent .md shape beyond tool names (Claude validator owns frontmatter)
+ *
+ * Cross-target imports are forbidden per §3.4 of the architecture spec.
+ *
+ * @see docs/specs/architecture.md §10 (validation contract), §8.1 (Finding types)
+ * @see docs/specs/architecture.md §12.5 (internal module shape), §3.4 (target isolation)
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { CLAUDE_TO_KIRO_TOOLS } from './transform.js';
+import { kiroMcpConfigSchema, kiroPowerMdFrontmatterSchema } from './schemas.js';
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Build a hard `schema-invalid` Finding scoped to `pluginName`. */
+function hardSchemaFinding(pluginName, message, hint) {
+    const finding = {
+        severity: 'hard',
+        code: 'schema-invalid',
+        plugin: pluginName,
+        message,
+    };
+    if (hint !== undefined) {
+        finding.hint = hint;
+    }
+    return finding;
+}
+/** Build a hard `name-consistency` Finding scoped to `pluginName`. */
+function hardNameFinding(pluginName, message, hint) {
+    const finding = {
+        severity: 'hard',
+        code: 'name-consistency',
+        plugin: pluginName,
+        message,
+    };
+    if (hint !== undefined) {
+        finding.hint = hint;
+    }
+    return finding;
+}
+/** Build a soft `schema-invalid` Finding scoped to `pluginName`. */
+function softSchemaFinding(pluginName, message, hint) {
+    const finding = {
+        severity: 'soft',
+        code: 'schema-invalid',
+        plugin: pluginName,
+        message,
+    };
+    if (hint !== undefined) {
+        finding.hint = hint;
+    }
+    return finding;
+}
+// ---------------------------------------------------------------------------
+// POWER.md validation
+// ---------------------------------------------------------------------------
+/**
+ * Validate POWER.md frontmatter:
+ *   - Parse YAML between `---` markers.
+ *   - Validate against `kiroPowerMdFrontmatterSchema`.
+ *   - Verify `name` matches `path.basename(pluginDir)`.
+ *
+ * Returns zero findings when POWER.md is absent (envelope-adherence owns that check).
+ */
+function validatePowerMd(pluginDir, pluginName) {
+    const powerMdPath = path.join(pluginDir, 'POWER.md');
+    if (!fs.existsSync(powerMdPath))
+        return [];
+    const content = fs.readFileSync(powerMdPath, 'utf-8');
+    // Extract frontmatter block between leading `---` markers.
+    const fmMatch = /^---\r?\n([\s\S]*?)\r?\n---/m.exec(content);
+    if (fmMatch === null) {
+        return [
+            hardSchemaFinding(pluginName, `POWER.md has no frontmatter block`, `add a YAML frontmatter block between --- markers at the top of POWER.md with required fields: name, description, version`),
+        ];
+    }
+    const frontmatterYaml = fmMatch[1] ?? '';
+    let parsed;
+    try {
+        parsed = parseYaml(frontmatterYaml);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return [
+            hardSchemaFinding(pluginName, `POWER.md frontmatter YAML parse error: ${msg}`, `fix the YAML syntax in the POWER.md frontmatter`),
+        ];
+    }
+    const result = kiroPowerMdFrontmatterSchema.safeParse(parsed);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
+            .join('; ');
+        return [
+            hardSchemaFinding(pluginName, `POWER.md frontmatter does not match schema — ${issues}`, `ensure POWER.md frontmatter includes required fields: name, description, version`),
+        ];
+    }
+    // Name-consistency check: frontmatter name must match the plugin directory name.
+    const frontmatterName = result.data.name;
+    if (frontmatterName !== pluginName) {
+        return [
+            hardNameFinding(pluginName, `POWER.md frontmatter name '${frontmatterName}' does not match plugin directory '${pluginName}'`, `set the name field in POWER.md frontmatter to '${pluginName}'`),
+        ];
+    }
+    return [];
+}
+// ---------------------------------------------------------------------------
+// mcp.json validation
+// ---------------------------------------------------------------------------
+/**
+ * If `mcp.json` exists, parse JSON and validate against `kiroMcpConfigSchema`.
+ * Missing file → no finding (envelope-adherence owns that check).
+ */
+function validateMcpJson(pluginDir, pluginName) {
+    const mcpPath = path.join(pluginDir, 'mcp.json');
+    if (!fs.existsSync(mcpPath))
+        return [];
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(mcpPath, 'utf-8'));
+    }
+    catch {
+        return [
+            hardSchemaFinding(pluginName, `mcp.json is not valid JSON`, `fix the JSON syntax in mcp.json`),
+        ];
+    }
+    const result = kiroMcpConfigSchema.safeParse(raw);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
+            .join('; ');
+        return [
+            hardSchemaFinding(pluginName, `mcp.json does not match the Kiro MCP config schema — ${issues}`, `ensure mcp.json has the shape { mcpServers: Record<string, { command: string, args?: string[], env?: Record<string, string> }> }`),
+        ];
+    }
+    return [];
+}
+// ---------------------------------------------------------------------------
+// Agent tool-name translation warnings
+// ---------------------------------------------------------------------------
+/**
+ * Extract the `tools` array from YAML frontmatter of a `.md` file.
+ * Returns an empty array if the file has no frontmatter or no `tools` field.
+ * Parse errors are silently ignored (the Claude validator owns frontmatter shape).
+ */
+function extractAgentTools(content) {
+    const fmMatch = /^---\r?\n([\s\S]*?)\r?\n---/m.exec(content);
+    if (fmMatch === null)
+        return [];
+    const frontmatterYaml = fmMatch[1] ?? '';
+    let parsed;
+    try {
+        parsed = parseYaml(frontmatterYaml);
+    }
+    catch {
+        return [];
+    }
+    if (typeof parsed !== 'object' ||
+        parsed === null ||
+        !('tools' in parsed) ||
+        !Array.isArray(parsed['tools'])) {
+        return [];
+    }
+    const tools = parsed['tools'];
+    return tools.filter((t) => typeof t === 'string');
+}
+/**
+ * For each `.md` file directly under `agents/` (one level deep), emit a soft
+ * `schema-invalid` finding for each tool name not present in `CLAUDE_TO_KIRO_TOOLS`.
+ *
+ * Severity is soft — unmapped tools are dropped from the Kiro bundle but do not
+ * block the build.
+ */
+function validateAgentToolNames(pluginDir, pluginName) {
+    const agentsDir = path.join(pluginDir, 'agents');
+    if (!fs.existsSync(agentsDir))
+        return [];
+    const entries = fs.readdirSync(agentsDir, { withFileTypes: true });
+    const findings = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.md'))
+            continue;
+        const agentName = entry.name.replace(/\.md$/, '');
+        const agentPath = path.join(agentsDir, entry.name);
+        const content = fs.readFileSync(agentPath, 'utf-8');
+        const tools = extractAgentTools(content);
+        for (const tool of tools) {
+            if (!(tool in CLAUDE_TO_KIRO_TOOLS)) {
+                findings.push(softSchemaFinding(pluginName, `agent '${agentName}' uses Claude tool '${tool}' which has no Kiro equivalent — it will be dropped from the Kiro bundle`, `remove '${tool}' from the tools list in agents/${entry.name}, or check the CLAUDE_TO_KIRO_TOOLS table for the correct Claude tool name`));
+            }
+        }
+    }
+    return findings;
+}
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+/**
+ * Run Kiro-specific validators against a plugin directory.
+ *
+ * `pluginDir` is the absolute path to a `plugins/<name>/` directory.
+ * All findings use `plugin: path.basename(pluginDir)`.
+ *
+ * Returns zero or more Findings. Callers combine these with other targets'
+ * findings and the cross-target findings in the pipeline validator.
+ */
+export function validateKiroPlugin(pluginDir) {
+    const pluginName = path.basename(pluginDir);
+    return [
+        ...validatePowerMd(pluginDir, pluginName),
+        ...validateMcpJson(pluginDir, pluginName),
+        ...validateAgentToolNames(pluginDir, pluginName),
+    ];
+}
+//# sourceMappingURL=validate.js.map

package/dist/targets/kiro/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../../src/targets/kiro/validate.ts"],"names":[],"mappings":"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"}

package/dist/targets/scaffold-kit.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Shared scaffold primitives for per-target scaffold modules.
+ *
+ * This module lives at `targets/` (not inside any single target folder), so importing it from a
+ * `targets/<target>/scaffold.ts` file does NOT violate the cross-target-import rule (§3.4) — that
+ * rule forbids importing from a *sibling target* folder, not from shared infrastructure.
+ *
+ * It carries no target-specific logic: only the common file-descriptor shape, the canonical
+ * `schemaVersion` literal (§12.2), and the per-target scaffold option bag.
+ *
+ * @see docs/specs/architecture.md §12.2 (schemaVersion on every manifest)
+ * @see docs/specs/architecture.md §12.5 (per-target scaffold.ts)
+ */
+/**
+ * Canonical `schemaVersion` literal emitted by every scaffolded manifest in this toolkit version.
+ * Pinned per §9.4 / §12.2 — a single value in v0.1.0.
+ */
+export declare const SCHEMA_VERSION = "0.1.0";
+/**
+ * A single file a target contributes to a scaffolded plugin.
+ *
+ * `path` is RELATIVE to the plugin directory (e.g. `.claude-plugin/plugin.json`). Content is the
+ * complete file body. Scaffold functions are pure — they never touch the filesystem.
+ */
+export interface ScaffoldedFile {
+    /** Path relative to the plugin directory. POSIX-style forward slashes. */
+    path: string;
+    /** Complete file content. */
+    content: string;
+}
+/**
+ * Options accepted by a per-target scaffold function.
+ *
+ * When `placeholder` is true (the `aipm add-target` path, §6.4), descriptive fields are emitted
+ * as empty/placeholder values for the author to fill in rather than auto-generated text.
+ */
+export interface TargetScaffoldOptions {
+    /** Human-readable plugin description. Omitted → a deterministic default per target. */
+    description?: string;
+    /**
+     * Emit blank manifest fields for the author to complete, per §6.4 "leaving manifest fields
+     * blank for the author". Used by `aipm add-target`. Default: false.
+     */
+    placeholder?: boolean;
+}
+/**
+ * Resolve the description to embed in a scaffolded manifest.
+ *
+ * - `placeholder` mode → empty string (author fills it in).
+ * - explicit `description` → used verbatim.
+ * - otherwise → a deterministic default derived from the plugin name.
+ *
+ * Deterministic: never reads the clock or environment (scaffold output must be reproducible).
+ */
+export declare function resolveDescription(pluginName: string, opts: TargetScaffoldOptions): string;
+//# sourceMappingURL=scaffold-kit.d.ts.map

package/dist/targets/scaffold-kit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold-kit.d.ts","sourceRoot":"","sources":["../../src/targets/scaffold-kit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;GAGG;AACH,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,uFAAuF;IACvF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,GAAG,MAAM,CAG1F"}

package/dist/targets/scaffold-kit.js

@@ -0,0 +1,33 @@
+/**
+ * Shared scaffold primitives for per-target scaffold modules.
+ *
+ * This module lives at `targets/` (not inside any single target folder), so importing it from a
+ * `targets/<target>/scaffold.ts` file does NOT violate the cross-target-import rule (§3.4) — that
+ * rule forbids importing from a *sibling target* folder, not from shared infrastructure.
+ *
+ * It carries no target-specific logic: only the common file-descriptor shape, the canonical
+ * `schemaVersion` literal (§12.2), and the per-target scaffold option bag.
+ *
+ * @see docs/specs/architecture.md §12.2 (schemaVersion on every manifest)
+ * @see docs/specs/architecture.md §12.5 (per-target scaffold.ts)
+ */
+/**
+ * Canonical `schemaVersion` literal emitted by every scaffolded manifest in this toolkit version.
+ * Pinned per §9.4 / §12.2 — a single value in v0.1.0.
+ */
+export const SCHEMA_VERSION = '0.1.0';
+/**
+ * Resolve the description to embed in a scaffolded manifest.
+ *
+ * - `placeholder` mode → empty string (author fills it in).
+ * - explicit `description` → used verbatim.
+ * - otherwise → a deterministic default derived from the plugin name.
+ *
+ * Deterministic: never reads the clock or environment (scaffold output must be reproducible).
+ */
+export function resolveDescription(pluginName, opts) {
+    if (opts.placeholder)
+        return '';
+    return opts.description ?? `A plugin for ${pluginName}`;
+}
+//# sourceMappingURL=scaffold-kit.js.map

package/dist/targets/scaffold-kit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold-kit.js","sourceRoot":"","sources":["../../src/targets/scaffold-kit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AA+BtC;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAAkB,EAAE,IAA2B;IAChF,IAAI,IAAI,CAAC,WAAW;QAAE,OAAO,EAAE,CAAC;IAChC,OAAO,IAAI,CAAC,WAAW,IAAI,gBAAgB,UAAU,EAAE,CAAC;AAC1D,CAAC"}

package/dist/targets/vercel/scaffold.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Scaffold templates for the Vercel Skills CLI target.
+ *
+ * `scaffoldVercelFiles` is a pure function returning the skeleton files this target contributes
+ * to a new plugin: a `skills/<name>/SKILL.md` whose YAML frontmatter is the complete Vercel
+ * surface (there is no separate plugin.json-like manifest). The frontmatter carries
+ * `schemaVersion: "0.1.0"` (§12.2). No generated-file sentinels — this is an author-authored
+ * skeleton file (§4.3).
+ *
+ * This module must not import from any sibling targets/<other>/ folder (§3.4).
+ *
+ * @see https://agentskills.io (SKILL.md frontmatter constraints)
+ * @see docs/specs/architecture.md §4 (plugin source layout)
+ * @see docs/specs/architecture.md §6.4 (compatibility-assist)
+ * @see docs/specs/architecture.md §12.2 (schemaVersion on every manifest)
+ * @see docs/specs/architecture.md §12.5 (per-target scaffold.ts)
+ */
+import { type ScaffoldedFile, type TargetScaffoldOptions } from '../scaffold-kit.js';
+/**
+ * Produce the Vercel skeleton files for a plugin.
+ *
+ * The minimum required artifact (validated specially in `validateEnvelopeAdherence`) is at least
+ * one `skills/<skill>/SKILL.md`. The scaffold seeds a single skill named after the plugin; the
+ * frontmatter satisfies `vercelSkillFrontmatterSchema` (`name` slug + non-empty `description`).
+ *
+ * The skill directory name MUST equal the frontmatter `name` (Stage 4 cross-validator); both are
+ * the plugin name here.
+ *
+ * @param pluginName - Plugin identity; used as the skill directory name and frontmatter `name`.
+ * @param opts - Optional description and add-target placeholder behaviour.
+ * @returns Files contributed by this target, with paths relative to the plugin directory.
+ */
+export declare function scaffoldVercelFiles(pluginName: string, opts?: TargetScaffoldOptions): ScaffoldedFile[];
+//# sourceMappingURL=scaffold.d.ts.map

package/dist/targets/vercel/scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../src/targets/vercel/scaffold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC3B,MAAM,oBAAoB,CAAC;AAK5B;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,qBAA0B,GAC/B,cAAc,EAAE,CAwBlB"}

package/dist/targets/vercel/scaffold.js

@@ -0,0 +1,58 @@
+/**
+ * Scaffold templates for the Vercel Skills CLI target.
+ *
+ * `scaffoldVercelFiles` is a pure function returning the skeleton files this target contributes
+ * to a new plugin: a `skills/<name>/SKILL.md` whose YAML frontmatter is the complete Vercel
+ * surface (there is no separate plugin.json-like manifest). The frontmatter carries
+ * `schemaVersion: "0.1.0"` (§12.2). No generated-file sentinels — this is an author-authored
+ * skeleton file (§4.3).
+ *
+ * This module must not import from any sibling targets/<other>/ folder (§3.4).
+ *
+ * @see https://agentskills.io (SKILL.md frontmatter constraints)
+ * @see docs/specs/architecture.md §4 (plugin source layout)
+ * @see docs/specs/architecture.md §6.4 (compatibility-assist)
+ * @see docs/specs/architecture.md §12.2 (schemaVersion on every manifest)
+ * @see docs/specs/architecture.md §12.5 (per-target scaffold.ts)
+ */
+import { resolveDescription, SCHEMA_VERSION, } from '../scaffold-kit.js';
+/** Identity tag enabling editor highlighting of the embedded Markdown body. */
+const md = String.raw;
+/**
+ * Produce the Vercel skeleton files for a plugin.
+ *
+ * The minimum required artifact (validated specially in `validateEnvelopeAdherence`) is at least
+ * one `skills/<skill>/SKILL.md`. The scaffold seeds a single skill named after the plugin; the
+ * frontmatter satisfies `vercelSkillFrontmatterSchema` (`name` slug + non-empty `description`).
+ *
+ * The skill directory name MUST equal the frontmatter `name` (Stage 4 cross-validator); both are
+ * the plugin name here.
+ *
+ * @param pluginName - Plugin identity; used as the skill directory name and frontmatter `name`.
+ * @param opts - Optional description and add-target placeholder behaviour.
+ * @returns Files contributed by this target, with paths relative to the plugin directory.
+ */
+export function scaffoldVercelFiles(pluginName, opts = {}) {
+    const description = resolveDescription(pluginName, opts);
+    // `description` is constrained to min length 1. In placeholder mode (add-target) we emit an
+    // empty value, intentionally leaving an incomplete-but-fillable skeleton per §6.4; the author
+    // completes it before the plugin validates.
+    const content = md `---
+schemaVersion: ${SCHEMA_VERSION}
+name: ${pluginName}
+description: ${JSON.stringify(description)}
+---
+
+# ${pluginName}
+
+${description}
+
+## Procedure
+
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+`;
+    return [{ path: `skills/${pluginName}/SKILL.md`, content }];
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/targets/vercel/scaffold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../../../src/targets/vercel/scaffold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACL,kBAAkB,EAClB,cAAc,GAGf,MAAM,oBAAoB,CAAC;AAE5B,+EAA+E;AAC/E,MAAM,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC;AAEtB;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CACjC,UAAkB,EAClB,OAA8B,EAAE;IAEhC,MAAM,WAAW,GAAG,kBAAkB,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IAEzD,4FAA4F;IAC5F,8FAA8F;IAC9F,4CAA4C;IAC5C,MAAM,OAAO,GAAG,EAAE,CAAA;iBACH,cAAc;QACvB,UAAU;eACH,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC;;;IAGtC,UAAU;;EAEZ,WAAW;;;;;;;CAOZ,CAAC;IAEA,OAAO,CAAC,EAAE,IAAI,EAAE,UAAU,UAAU,WAAW,EAAE,OAAO,EAAE,CAAC,CAAC;AAC9D,CAAC"}

package/dist/targets/vercel/schemas.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Zod schemas for the Vercel Skills CLI target.
+ *
+ * The primary artifact for the Vercel target is `SKILL.md` — a markdown file with YAML
+ * frontmatter consumed by the Vercel Skills CLI per the agentskills.io spec. There is no
+ * `plugin.json`-like manifest; `SKILL.md` is the complete surface.
+ *
+ * This module must not import from any sibling targets/<other>/ folder (§3.4).
+ *
+ * Note on ownership: `SKILL.md` is also consumed by Claude, Cursor, Gemini, and Kiro
+ * (via steering), but the schema lives here because Vercel's primary surface is SKILL.md.
+ * A future refactor may move it to a shared module (see §16 open questions).
+ *
+ * schemaVersion: accepted but not validated in v0.1.0 per §9.4 and §12.2.
+ *
+ * @see https://agentskills.io (agentskills.io spec — source of name/description constraints)
+ */
+import { z } from 'zod';
+/** Maximum byte length for a skill `name` field per agentskills.io spec. */
+export declare const SKILL_NAME_MAX_LENGTH = 64;
+/** Maximum byte length for a skill `description` field per agentskills.io spec. */
+export declare const SKILL_DESCRIPTION_MAX_LENGTH = 1024;
+/**
+ * Schema for the YAML frontmatter of `SKILL.md` files per the agentskills.io spec.
+ *
+ * Constraints faithfully ported from `validateSkillFrontmatter` in the template repo:
+ *   - `name`: lowercase-alphanumeric-with-hyphens slug, max 64 chars, must start with a
+ *     letter, no consecutive hyphens (`--`), no trailing hyphen.
+ *   - `description`: non-empty string, max 1024 chars.
+ *
+ * `.loose()` (passthrough) is used at the top level because authors may add
+ * platform-specific keys (e.g., Claude's `model`, `tools`, `color`).
+ *
+ * Parent-directory-name matching is a Stage 4 cross-validator concern — not enforced here.
+ * Body line-count (soft 500-line recommendation) is informational — not enforced here.
+ */
+export declare const vercelSkillFrontmatterSchema: z.ZodObject<{
+    schemaVersion: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+    description: z.ZodString;
+}, z.core.$loose>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/targets/vercel/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../src/targets/vercel/schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,4EAA4E;AAC5E,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC,mFAAmF;AACnF,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAMjD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,4BAA4B;;;;iBA8B/B,CAAC"}

package/dist/targets/vercel/schemas.js

@@ -0,0 +1,69 @@
+/**
+ * Zod schemas for the Vercel Skills CLI target.
+ *
+ * The primary artifact for the Vercel target is `SKILL.md` — a markdown file with YAML
+ * frontmatter consumed by the Vercel Skills CLI per the agentskills.io spec. There is no
+ * `plugin.json`-like manifest; `SKILL.md` is the complete surface.
+ *
+ * This module must not import from any sibling targets/<other>/ folder (§3.4).
+ *
+ * Note on ownership: `SKILL.md` is also consumed by Claude, Cursor, Gemini, and Kiro
+ * (via steering), but the schema lives here because Vercel's primary surface is SKILL.md.
+ * A future refactor may move it to a shared module (see §16 open questions).
+ *
+ * schemaVersion: accepted but not validated in v0.1.0 per §9.4 and §12.2.
+ *
+ * @see https://agentskills.io (agentskills.io spec — source of name/description constraints)
+ */
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// Constants (exported so Stage 4 validators can reference without re-deriving)
+// ---------------------------------------------------------------------------
+/** Maximum byte length for a skill `name` field per agentskills.io spec. */
+export const SKILL_NAME_MAX_LENGTH = 64;
+/** Maximum byte length for a skill `description` field per agentskills.io spec. */
+export const SKILL_DESCRIPTION_MAX_LENGTH = 1024;
+// ---------------------------------------------------------------------------
+// vercelSkillFrontmatterSchema
+// ---------------------------------------------------------------------------
+/**
+ * Schema for the YAML frontmatter of `SKILL.md` files per the agentskills.io spec.
+ *
+ * Constraints faithfully ported from `validateSkillFrontmatter` in the template repo:
+ *   - `name`: lowercase-alphanumeric-with-hyphens slug, max 64 chars, must start with a
+ *     letter, no consecutive hyphens (`--`), no trailing hyphen.
+ *   - `description`: non-empty string, max 1024 chars.
+ *
+ * `.loose()` (passthrough) is used at the top level because authors may add
+ * platform-specific keys (e.g., Claude's `model`, `tools`, `color`).
+ *
+ * Parent-directory-name matching is a Stage 4 cross-validator concern — not enforced here.
+ * Body line-count (soft 500-line recommendation) is informational — not enforced here.
+ */
+export const vercelSkillFrontmatterSchema = z
+    .object({
+    /** Reserved for future migrex adoption. Accepted but not validated in v0.1.0. */
+    schemaVersion: z.string().optional(),
+    /**
+     * Skill identifier. Must be a lowercase alphanumeric slug:
+     *   - Starts with `[a-z]`
+     *   - Contains only `[a-z0-9-]`
+     *   - Maximum 64 characters
+     *   - No consecutive hyphens (`--`)
+     *   - Does not end with a hyphen
+     */
+    name: z
+        .string()
+        .regex(/^[a-z][a-z0-9-]*$/, 'name must be lowercase alphanumeric with hyphens, starting with a letter')
+        .max(SKILL_NAME_MAX_LENGTH)
+        .refine((v) => !v.includes('--'), {
+        message: 'name must not contain consecutive hyphens',
+    })
+        .refine((v) => !v.endsWith('-'), {
+        message: 'name must not end with a hyphen',
+    }),
+    /** What this skill does. Non-empty, maximum 1024 characters. */
+    description: z.string().min(1).max(SKILL_DESCRIPTION_MAX_LENGTH),
+})
+    .loose();
+//# sourceMappingURL=schemas.js.map

package/dist/targets/vercel/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../../src/targets/vercel/schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,8EAA8E;AAC9E,+EAA+E;AAC/E,8EAA8E;AAE9E,4EAA4E;AAC5E,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAExC,mFAAmF;AACnF,MAAM,CAAC,MAAM,4BAA4B,GAAG,IAAI,CAAC;AAEjD,8EAA8E;AAC9E,+BAA+B;AAC/B,8EAA8E;AAE9E;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC;KAC1C,MAAM,CAAC;IACN,iFAAiF;IACjF,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAEpC;;;;;;;OAOG;IACH,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,KAAK,CACJ,mBAAmB,EACnB,0EAA0E,CAC3E;SACA,GAAG,CAAC,qBAAqB,CAAC;SAC1B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE;QAChC,OAAO,EAAE,2CAA2C;KACrD,CAAC;SACD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE;QAC/B,OAAO,EAAE,iCAAiC;KAC3C,CAAC;IAEJ,gEAAgE;IAChE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,4BAA4B,CAAC;CACjE,CAAC;KACD,KAAK,EAAE,CAAC"}

package/dist/targets/vercel/validate.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Per-target validators for the Vercel Skills CLI target.
+ *
+ * The Vercel target's primary authored artifact is `SKILL.md` — one file per
+ * skill directory under `plugins/<name>/skills/<skill-name>/SKILL.md`. This
+ * module validates:
+ *   1. YAML frontmatter presence and schema conformance.
+ *   2. Name/parent-directory consistency (the agentskills.io spec requires that
+ *      a skill's frontmatter `name` matches the name of its immediate parent
+ *      directory).
+ *   3. Body line-count recommendation (soft finding when body exceeds 500 lines).
+ *
+ * Cross-target concerns (envelope-adherence, name-consistency, mcp-key-sync,
+ * marketplace-registration, freshness) are out of scope for this module.
+ *
+ * @see docs/specs/architecture.md §10 (validation contract), §8.1 (Finding types)
+ * @see https://agentskills.io (agentskills.io spec — source of name/description constraints)
+ */
+import type { Finding } from '../../pipeline/types.js';
+/**
+ * Run Vercel-specific validators (SKILL.md shape and name consistency)
+ * against a plugin directory.
+ *
+ * `pluginDir` is the absolute path to a `plugins/<name>/` directory.
+ * All findings use `plugin: path.basename(pluginDir)`.
+ */
+export declare function validateVercelPlugin(pluginDir: string): Finding[];
+//# sourceMappingURL=validate.d.ts.map

package/dist/targets/vercel/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/targets/vercel/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAOH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAuLvD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,EAAE,CAUjE"}