dsh-skill-importer 0.2.0 → 0.2.1

package/README.md

@@ -53,26 +53,68 @@ All three fill the composer with the same highlighted `/name ` gesture; sending
 
 ## Installation
 
-### 1. Add the plugin to the Web profile
+### First install
 
 ```sh
-dsh plugin --profile web add dsh-skill-importer
+npx @deepseek-ai/dsh plugin --profile web add dsh-skill-importer@latest
 ```
 
-### 2. Enable it in the profile
+The plugin registers itself with the Web profile through `dsh.bundle`; do not edit `cordis.patch.yml` manually.
 
-Add the following entry to `$DSH_HOME/profiles/web/cordis.patch.yml`:
+Restart dsh Web after installation:
+
+```sh
+npx @deepseek-ai/dsh web
+```
+
+### Update to the latest version
+
+Existing users can run the same command to update:
+
+```sh
+npx @deepseek-ai/dsh plugin --profile web add dsh-skill-importer@latest
+```
+
+Updating replaces only the plugin package. It does not remove project skills in `.agents/skills` or global skills in `~/.dsh/skills`. Restart dsh Web after updating.
+
+Check the latest published version:
+
+```sh
+npm view dsh-skill-importer version
+```
+
+List the plugins installed in the Web profile:
+
+```sh
+npx @deepseek-ai/dsh plugin --profile web list
+```
+
+#### Supply-chain waiting period for new releases
+
+DSH profiles use pnpm to manage plugins. pnpm's `minimumReleaseAge` policy delays newly published versions; during that window, `@latest` may still resolve to the previous mature release. This is an intentional supply-chain safeguard, not a download failure. The recommended path is to wait for the profile's configured window, then rerun the `@latest` command above.
+
+Pre-1.0 semver ranges also stop at the next minor: for example, `^0.1.2` does not include `0.2.0`. After the waiting period, specify the target version when crossing a minor:
+
+```sh
+npx @deepseek-ai/dsh plugin --profile web add dsh-skill-importer@X.Y.Z
+```
+
+If you have verified the release and must install it immediately, add a temporary exception for that **exact version** to `$DSH_HOME/profiles/web/pnpm-workspace.yaml`, then run the exact-version command:
 
 ```yaml
-- id: skill-importer
-  name: dsh-skill-importer
+minimumReleaseAgeExclude:
+  - dsh-skill-importer@X.Y.Z
 ```
 
-### 3. Restart dsh Web
+Replace both `X.Y.Z` placeholders with the same target version. This opts that version out of the supply-chain waiting period. Do not permanently exempt the package name; remove the exact-version exception after the release matures.
 
 Open **Settings → Skills**. Import a Markdown file or URL, or choose **Batch import** to migrate another agent's complete skills directory. Choose a target and the imported skills will appear as soon as the filesystem watcher discovers them.
 
-> Requires DeepSeek Harness `>= 0.1.0-rc.6` via `npx @deepseek-ai/dsh web`.
+> Requires DeepSeek Harness `>= 0.1.0-rc.6`.
+
+### Duplicate plugin after upgrading
+
+If startup fails with `duplicate loader entry id: skill-importer`, the profile still contains the old manual configuration. Remove the manually added `skill-importer` entry from `$DSH_HOME/profiles/web/cordis.patch.yml`, then restart dsh Web. Current releases register automatically and do not need that entry.
 
 ## How it works
 
@@ -124,13 +166,13 @@ npm run build
 dsh plugin --profile web add /path/to/dsh-skill-importer
 ```
 
-Add the profile entry shown above, then restart dsh Web.
+If `dsh` is not installed globally, replace the last line with `npx @deepseek-ai/dsh plugin --profile web add /path/to/dsh-skill-importer`. The plugin registers automatically; restart dsh Web afterward.
 
 ## Notes
 
 - A single imported file may be up to 256 KB.
-- Batch import accepts up to 200 skills per scan; each skill may contain up to 2,000 files and 10 MB of resources. Symbolic links are refused.
-- URL import preserves `.md` sources; HTML pages use lightweight text extraction, so direct Markdown URLs work best.
+- Batch import accepts `.claude/skills`, `.codex/skills`, `.agents/skills`, `.dsh/skills`, or one skill directory directly below those roots. A scan accepts up to 200 skills; each skill may contain up to 2,000 files and 10 MB of resources. Symbolic links are refused.
+- URL import is HTTPS-only and refuses loopback, private, link-local, and reserved addresses; every redirect is validated again. `.md` sources are preserved, while HTML pages use lightweight text extraction, so direct Markdown URLs work best.
 - The installed list polls briefly after import (every 2 seconds for up to 20 seconds). **Refresh** syncs external changes immediately.
 
 ## License

package/README.zh.md

@@ -53,26 +53,68 @@
 
 ## 安装
 
-### 1. 安装到 Web profile
+### 首次安装
 
 ```sh
-dsh plugin --profile web add dsh-skill-importer
+npx @deepseek-ai/dsh plugin --profile web add dsh-skill-importer@latest
 ```
 
-### 2. 在 profile 中启用
+插件通过 `dsh.bundle` 自动注册到 Web profile，无需手动修改 `cordis.patch.yml`。
 
-向 `$DSH_HOME/profiles/web/cordis.patch.yml` 添加：
+安装完成后重启 dsh Web：
+
+```sh
+npx @deepseek-ai/dsh web
+```
+
+### 更新到最新版
+
+已安装用户执行同一条命令即可更新：
+
+```sh
+npx @deepseek-ai/dsh plugin --profile web add dsh-skill-importer@latest
+```
+
+更新只会替换插件包，不会删除 `.agents/skills` 中的项目技能或 `~/.dsh/skills` 中的全局技能。更新后请重启 dsh Web。
+
+查看 npm 上的最新版本：
+
+```sh
+npm view dsh-skill-importer version
+```
+
+查看 Web profile 中已安装的插件：
+
+```sh
+npx @deepseek-ai/dsh plugin --profile web list
+```
+
+#### 新版本的安全等待期
+
+DSH profile 使用 pnpm 管理插件。pnpm 会按 `minimumReleaseAge` 暂缓安装刚发布的版本；在等待期内，`@latest` 可能仍解析到上一个已成熟版本。这是供应链保护机制，不是下载失败。推荐等待 profile 配置的时间窗口结束后，再执行上面的 `@latest` 命令。
+
+`0.x` 版本还遵循特殊的 semver 范围：例如 `^0.1.2` 不包含 `0.2.0`。跨 minor 更新时可在等待期结束后明确指定目标版本：
+
+```sh
+npx @deepseek-ai/dsh plugin --profile web add dsh-skill-importer@X.Y.Z
+```
+
+如果已经核验该版本并且必须立即安装，可在 `$DSH_HOME/profiles/web/pnpm-workspace.yaml` 中为这个**精确版本**添加临时信任例外，再执行精确版本命令：
 
 ```yaml
-- id: skill-importer
-  name: dsh-skill-importer
+minimumReleaseAgeExclude:
+  - dsh-skill-importer@X.Y.Z
 ```
 
-### 3. 重启 dsh Web
+将两处 `X.Y.Z` 替换为同一个目标版本。这会绕过该版本的供应链等待期，不建议把包名永久加入例外列表。版本成熟后可以删除这条例外。
 
 打开 **设置 → 技能**，选择 Markdown 文件、粘贴 URL，或通过「批量导入」迁移其他 Agent 的完整技能目录，再选择目标范围。文件系统 watcher 发现后，技能会立即出现。
 
-> 需要 DeepSeek Harness `>= 0.1.0-rc.6`，使用 `npx @deepseek-ai/dsh web` 运行。
+> 需要 DeepSeek Harness `>= 0.1.0-rc.6`。
+
+### 旧配置导致重复插件
+
+如果启动时报错 `duplicate loader entry id: skill-importer`，说明 profile 中还保留了旧版手动配置。请从 `$DSH_HOME/profiles/web/cordis.patch.yml` 删除手动添加的 `skill-importer` 条目，再重启 dsh Web。当前版本会自动注册，不需要保留该条目。
 
 ## 工作原理
 
@@ -124,13 +166,13 @@ npm run build
 dsh plugin --profile web add /path/to/dsh-skill-importer
 ```
 
-随后添加上文的 profile 配置并重启 dsh Web。
+如果没有全局 `dsh` 命令，可将最后一行替换为 `npx @deepseek-ai/dsh plugin --profile web add /path/to/dsh-skill-importer`。插件会自动注册，随后重启 dsh Web 即可。
 
 ## 注意事项
 
 - 单个导入文件最大 256 KB。
-- 批量导入每次最多扫描 200 个技能；单个技能最多包含 2,000 个文件和 10 MB 资源，不接受符号链接。
-- URL 导入会原样保留 `.md`；HTML 页面仅做轻量正文提取，因此推荐使用 Markdown 直链。
+- 批量导入仅接受 `.claude/skills`、`.codex/skills`、`.agents/skills`、`.dsh/skills` 或其中的单个技能目录；每次最多扫描 200 个技能，单个技能最多包含 2,000 个文件和 10 MB 资源，不接受符号链接。
+- URL 导入仅支持 HTTPS，并拒绝本机、私有网络、链路本地和保留地址；每次重定向都会重新校验。`.md` 会原样保留，HTML 页面仅做轻量正文提取，因此推荐使用 Markdown 直链。
 - 导入后列表会短暂轮询（每 2 秒一次，最多 20 秒）；外部改动可点击 **刷新** 立即同步。
 
 ## License

package/lib/client.js

@@ -44,17 +44,18 @@ window.__ModuleLoader__.load({
 		*/
 		function parseSkillFile(text) {
 			const frontmatter = {};
-			if (!text.startsWith("---\n")) return {
+			const normalized = text.replace(/\r\n?/g, "\n");
+			if (!normalized.startsWith("---\n")) return {
 				frontmatter,
 				body: text
 			};
-			const end = text.indexOf("\n---", 4);
+			const end = normalized.indexOf("\n---", 4);
 			if (end < 0) return {
 				frontmatter,
 				body: text
 			};
-			const block = text.slice(4, end);
-			const body = text.slice(end + 4).replace(/^\n/, "");
+			const block = normalized.slice(4, end);
+			const body = normalized.slice(end + 4).replace(/^\n/, "");
 			for (const line of block.split("\n")) {
 				const colon = line.indexOf(":");
 				if (colon <= 0) continue;

package/lib/index.js

@@ -1,7 +1,9 @@
-import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { createHash, randomUUID } from "node:crypto";
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
 import { homedir } from "node:os";
-import { basename, extname, isAbsolute, join, relative } from "node:path";
+import { basename, dirname, extname, isAbsolute, join, relative } from "node:path";
 //#region src/frontmatter.ts
 /** Kebab-case name rule shared with `dsh-skill` (`^[a-z0-9]+(?:-[a-z0-9]+)*$`). */
 const KEBAB_CASE$1 = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -39,17 +41,18 @@ function parseScalar(raw) {
 */
 function parseSkillFile(text) {
 	const frontmatter = {};
-	if (!text.startsWith("---\n")) return {
+	const normalized = text.replace(/\r\n?/g, "\n");
+	if (!normalized.startsWith("---\n")) return {
 		frontmatter,
 		body: text
 	};
-	const end = text.indexOf("\n---", 4);
+	const end = normalized.indexOf("\n---", 4);
 	if (end < 0) return {
 		frontmatter,
 		body: text
 	};
-	const block = text.slice(4, end);
-	const body = text.slice(end + 4).replace(/^\n/, "");
+	const block = normalized.slice(4, end);
+	const body = normalized.slice(end + 4).replace(/^\n/, "");
 	for (const line of block.split("\n")) {
 		const colon = line.indexOf(":");
 		if (colon <= 0) continue;
@@ -96,6 +99,13 @@ const MAX_BATCH_FILES_PER_SKILL = 2e3;
 const MAX_BATCH_SKILL_BYTES = 10485760;
 const BATCH_SCAN_TTL_MS = 6e5;
 const KEBAB_CASE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const AGENT_SKILL_PARENTS = /* @__PURE__ */ new Set([
+	".agents",
+	".claude",
+	".codex",
+	".dsh"
+]);
+const MAX_URL_REDIRECTS = 5;
 /** The harness home (`$DSH_HOME`, defaulting to `~/.dsh`). */
 function dshHomeDir() {
 	return process.env.DSH_HOME ?? join(homedir(), ".dsh");
@@ -300,8 +310,15 @@ function batchSources(root) {
 function scanBatch(request) {
 	if (!isAbsolute(request.sourcePath)) throw new Error("批量导入目录必须是绝对路径");
 	if (!existsSync(request.sourcePath) || !statSync(request.sourcePath).isDirectory()) throw new Error("批量导入目录不存在或不可读");
+	const sourcePath = realpathSync(request.sourcePath);
+	const leaf = basename(sourcePath);
+	const parent = basename(dirname(sourcePath));
+	const grandparent = basename(dirname(dirname(sourcePath)));
+	const isSkillsRoot = leaf === "skills" && AGENT_SKILL_PARENTS.has(parent);
+	const isSkillDirectory = parent === "skills" && AGENT_SKILL_PARENTS.has(grandparent);
+	if (!isSkillsRoot && !isSkillDirectory) throw new Error("批量导入仅支持 .claude、.codex、.agents 或 .dsh 下的 skills 目录");
 	if (request.target !== "user" && request.workspacePath === void 0) throw new Error("项目目标需要 workspacePath（当前工作区路径）");
-	const sources = batchSources(request.sourcePath);
+	const sources = batchSources(sourcePath);
 	if (sources.length === 0) throw new Error("所选目录中没有找到可导入的技能");
 	if (sources.length > 200) throw new Error(`一次最多扫描 200 个技能`);
 	const entries = [];
@@ -309,7 +326,7 @@ function scanBatch(request) {
 	const nameRows = /* @__PURE__ */ new Map();
 	for (const [index, source] of sources.entries()) {
 		const id = String(index + 1);
-		const relativePath = relative(request.sourcePath, source.path) || ".";
+		const relativePath = relative(sourcePath, source.path) || ".";
 		try {
 			const skillFile = source.kind === "directory" ? join(source.path, "SKILL.md") : source.path;
 			const text = readFileSync(skillFile, "utf8");
@@ -367,7 +384,7 @@ function scanBatch(request) {
 	}
 	return {
 		scanId: randomUUID(),
-		sourcePath: request.sourcePath,
+		sourcePath,
 		target: request.target,
 		...request.workspacePath === void 0 ? {} : { workspacePath: request.workspacePath },
 		expiresAt: Date.now() + BATCH_SCAN_TTL_MS,
@@ -485,11 +502,61 @@ function extractHtmlText(html) {
 * @param url - the source URL.
 * @returns the text to write as the skill body.
 */
+function privateIpv4(address) {
+	const octets = address.split(".").map(Number);
+	if (octets.length !== 4 || octets.some((value) => !Number.isInteger(value) || value < 0 || value > 255)) return true;
+	const [a = 0, b = 0, c = 0] = octets;
+	return a === 0 || a === 10 || a === 127 || a >= 224 || a === 100 && b >= 64 && b <= 127 || a === 169 && b === 254 || a === 172 && b >= 16 && b <= 31 || a === 192 && (b === 0 || b === 168 || b === 0 && c === 2) || a === 198 && (b === 18 || b === 19 || b === 51 && c === 100) || a === 203 && b === 0 && c === 113;
+}
+/** Whether an address is unsafe for a host-side URL import. */
+function isPrivateAddress(address) {
+	const normalized = address.toLowerCase().split("%")[0] ?? "";
+	if (isIP(normalized) === 4) return privateIpv4(normalized);
+	if (isIP(normalized) !== 6) return true;
+	if (normalized.startsWith("::ffff:")) return privateIpv4(normalized.slice(7));
+	return normalized === "::" || normalized === "::1" || normalized.startsWith("fc") || normalized.startsWith("fd") || /^fe[89ab]/.test(normalized) || normalized.startsWith("ff") || normalized.startsWith("2001:db8:");
+}
+const resolveHost = async (hostname) => lookup(hostname, {
+	all: true,
+	verbatim: true
+});
+/** Parse and resolve one URL before the host is allowed to request it. */
+async function assertSafeImportUrl(input, resolver = resolveHost) {
+	let url;
+	try {
+		url = new URL(input);
+	} catch {
+		throw new Error("URL 格式无效");
+	}
+	if (url.protocol !== "https:") throw new Error("URL 导入仅支持 HTTPS");
+	if (url.username.length > 0 || url.password.length > 0) throw new Error("URL 不能包含登录凭据");
+	const hostname = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+	if (hostname === "localhost" || hostname.endsWith(".localhost")) throw new Error("URL 不能指向本机或私有网络");
+	const addresses = isIP(hostname) === 0 ? await resolver(hostname) : [{ address: hostname }];
+	if (addresses.length === 0 || addresses.some(({ address }) => isPrivateAddress(address))) throw new Error("URL 不能指向本机、私有网络或保留地址");
+	return url;
+}
 async function fetchUrlContent(url) {
-	const response = await fetch(url, {
-		redirect: "follow",
-		signal: AbortSignal.timeout(15e3)
-	});
+	let current = await assertSafeImportUrl(url);
+	let response;
+	for (let redirects = 0; redirects <= MAX_URL_REDIRECTS; redirects += 1) {
+		response = await fetch(current, {
+			redirect: "manual",
+			signal: AbortSignal.timeout(15e3)
+		});
+		if (![
+			301,
+			302,
+			303,
+			307,
+			308
+		].includes(response.status)) break;
+		if (redirects === MAX_URL_REDIRECTS) throw new Error(`重定向次数超过 ${MAX_URL_REDIRECTS}`);
+		const location = response.headers.get("location");
+		if (location === null) throw new Error("重定向响应缺少 Location");
+		current = await assertSafeImportUrl(new URL(location, current).href);
+	}
+	if (response === void 0) throw new Error("抓取失败");
 	if (!response.ok) throw new Error(`抓取失败：HTTP ${response.status}`);
 	const type = response.headers.get("content-type") ?? "";
 	const text = await response.text();
@@ -533,11 +600,12 @@ function readJsonBody(req, limit = MAX_BODY_BYTES) {
 * Origin fence: the routes are served on the harness's loopback-only web
 * server, so only the browser page itself (or a local curl) reaches them.
 * A cross-origin page (any other website) is refused. Requests without an
-* Origin header (curl, same-origin GET) pass.
+* Origin header is rejected: all state-changing browser requests include it,
+* while accepting an absent header would let non-browser clients bypass the fence.
 */
 function originAllowed(req) {
 	const origin = req.headers.origin;
-	if (origin === void 0) return true;
+	if (origin === void 0) return false;
 	try {
 		const hostname = new URL(origin).hostname;
 		return hostname === "127.0.0.1" || hostname === "localhost";

package/lib/types/server.d.ts

@@ -81,13 +81,13 @@ export interface BatchScanSession {
 export declare function scanBatch(request: BatchScanRequest): BatchScanSession;
 /** Commit a valid, unexpired scan once; invalid rows are returned as errors and never written. */
 export declare function commitBatch(session: BatchScanSession, replaceNames: ReadonlySet<string>): BatchCommitEntry[];
-/**
- * Fetch a URL's content for import. Markdown/plain responses pass through
- * verbatim; HTML is roughly extracted to text (the import UI recommends
- * `.md` sources).
- * @param url - the source URL.
- * @returns the text to write as the skill body.
- */
+/** Whether an address is unsafe for a host-side URL import. */
+export declare function isPrivateAddress(address: string): boolean;
+type ResolveHost = (hostname: string) => Promise<readonly {
+    readonly address: string;
+}[]>;
+/** Parse and resolve one URL before the host is allowed to request it. */
+export declare function assertSafeImportUrl(input: string, resolver?: ResolveHost): Promise<URL>;
 export declare function fetchUrlContent(url: string): Promise<string>;
 /**
  * Resolve one import request into a written file path. Shared by the file
@@ -102,7 +102,8 @@ export declare function readJsonBody(req: IncomingMessage, limit?: number): Prom
  * Origin fence: the routes are served on the harness's loopback-only web
  * server, so only the browser page itself (or a local curl) reaches them.
  * A cross-origin page (any other website) is refused. Requests without an
- * Origin header (curl, same-origin GET) pass.
+ * Origin header is rejected: all state-changing browser requests include it,
+ * while accepting an absent header would let non-browser clients bypass the fence.
  */
 export declare function originAllowed(req: IncomingMessage): boolean;
 /** Send one JSON response. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-skill-importer",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Web UI plugin for DeepSeek Harness: import skills from local Markdown files or URLs into the skill roots the harness discovers automatically",
   "type": "module",
   "main": "lib/index.js",
@@ -36,7 +36,11 @@
     "lib/index.js",
     "lib/client.js",
     "lib/types/**/*.d.ts",
-    "cordis.patch.yml"
+    "cordis.patch.yml",
+    "src/frontmatter.ts",
+    "src/server.ts",
+    "src/types.ts",
+    "tests/**/*.mjs"
   ],
   "scripts": {
     "build": "rm -rf lib && tsc -p tsconfig.json && tsdown",

package/src/frontmatter.ts

@@ -0,0 +1,112 @@
+/**
+ * Skill Markdown frontmatter parsing and validation (pure, browser-safe).
+ *
+ * Mirrors the subset of `dsh-skill-filesystem`'s frontmatter contract the
+ * import UI needs for preview and pre-flight validation. The authoritative
+ * parse remains the host provider's; this parser only previews and catches
+ * obvious mistakes before the import instruction is sent.
+ */
+
+/** Frontmatter fields the import UI understands. */
+export interface SkillFrontmatter {
+  /** Kebab-case skill name (required for a valid skill). */
+  name?: string
+  /** One-line routing description (required for a valid skill). */
+  description?: string
+  /** Optional routing guidance. */
+  whenToUse?: string
+  /** `disable-model-invocation: true` keeps the skill out of model catalogs. */
+  disableModelInvocation?: boolean
+  /** `user-invocable: false` keeps the skill out of the `/` menu. */
+  userInvocable?: boolean
+}
+
+/** Parsed Markdown file: frontmatter plus the body after it. */
+export interface ParsedSkillFile {
+  /** Parsed frontmatter values (empty when the file has no frontmatter block). */
+  readonly frontmatter: SkillFrontmatter
+  /** Markdown body after the closing `---` (empty when absent). */
+  readonly body: string
+}
+
+/** Kebab-case name rule shared with `dsh-skill` (`^[a-z0-9]+(?:-[a-z0-9]+)*$`). */
+const KEBAB_CASE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+/** True when the name satisfies the harness skill-name rule. */
+export function isValidSkillName(name: string): boolean {
+  return KEBAB_CASE.test(name)
+}
+
+const BOOLEAN_TRUE = new Set(['true', 'yes', 'on', '1'])
+const BOOLEAN_FALSE = new Set(['false', 'no', 'off', '0'])
+
+/** Parse one frontmatter scalar: quoted strings, booleans, or plain text. */
+function parseScalar(raw: string): string | boolean | undefined {
+  const value = raw.trim()
+  if (value.length === 0) return undefined
+  const lower = value.toLowerCase()
+  if (BOOLEAN_TRUE.has(lower)) return true
+  if (BOOLEAN_FALSE.has(lower)) return false
+  if (
+    (value.startsWith('"') && value.endsWith('"') && value.length >= 2)
+    || (value.startsWith("'") && value.endsWith("'") && value.length >= 2)
+  ) {
+    return value.slice(1, -1)
+  }
+  return value
+}
+
+/**
+ * Parse a skill Markdown file's frontmatter block.
+ * @param text - full file text.
+ * @returns parsed frontmatter and body; a file without a leading `---` block
+ *   yields an empty frontmatter with the whole text as body.
+ */
+export function parseSkillFile(text: string): ParsedSkillFile {
+  const frontmatter: SkillFrontmatter = {}
+  // Normalize platform line endings before locating and parsing the YAML
+  // fence. This accepts Windows CRLF and legacy CR files while keeping the
+  // canonical output produced by normalizeSkillText consistently LF-based.
+  const normalized = text.replace(/\r\n?/g, '\n')
+  if (!normalized.startsWith('---\n')) return { frontmatter, body: text }
+  const end = normalized.indexOf('\n---', 4)
+  if (end < 0) return { frontmatter, body: text }
+  const block = normalized.slice(4, end)
+  const body = normalized.slice(end + 4).replace(/^\n/, '')
+  for (const line of block.split('\n')) {
+    const colon = line.indexOf(':')
+    if (colon <= 0) continue
+    const key = line.slice(0, colon).trim()
+    const value = parseScalar(line.slice(colon + 1))
+    if (value === undefined) continue
+    switch (key) {
+      case 'name':
+        if (typeof value === 'string') frontmatter.name = value
+        break
+      case 'description':
+        if (typeof value === 'string') frontmatter.description = value
+        break
+      case 'whenToUse':
+        if (typeof value === 'string') frontmatter.whenToUse = value
+        break
+      case 'disable-model-invocation':
+        if (typeof value === 'boolean') frontmatter.disableModelInvocation = value
+        break
+      case 'user-invocable':
+        if (typeof value === 'boolean') frontmatter.userInvocable = value
+        break
+      default:
+        break
+    }
+  }
+  return { frontmatter, body }
+}
+
+/** Why a parsed file cannot be imported as a skill (or undefined when it can). */
+export function validateSkillFile(text: string): string | undefined {
+  const { frontmatter } = parseSkillFile(text)
+  if (frontmatter.name === undefined || frontmatter.name.length === 0) return 'frontmatter 缺少 name 字段'
+  if (!isValidSkillName(frontmatter.name)) return 'name 必须是 kebab-case（小写字母、数字、短横线）'
+  if (frontmatter.description === undefined || frontmatter.description.length === 0) return 'frontmatter 缺少 description 字段'
+  return undefined
+}