pi-profile-switch 0.8.0 → 0.9.1

package/README.md

@@ -36,7 +36,9 @@ Profiles live in two directories, with one JSON file per profile:
 
 Create or change a profile by editing or creating a `<name>.json` file directly — schema: [`schemas/profiles.schema.json`](schemas/profiles.schema.json).
 
-On install, pi-profile-switch seeds the global `profiles/` directory with a starter **`ask`** profile (`ask.json`) — read-only Q&A and code exploration. It assumes nothing about your setup; edit or delete it freely:
+You can also configure profiles conversationally: the package ships a **`profile-config`** skill (distributed to `<agentDir>/skills/profile-config/` — best-effort on install, and guaranteed in place at every launcher startup) that guides the agent to clarify requirements, discover resources, and write or remove profile files. Profiles created with a `skills` list include `"profile-config"` by default (unless explicitly opted out or covered by a wildcard like `"*"`), keeping configuration available after switching. Details: [`skills/profile-config/SKILL.md`](skills/profile-config/SKILL.md).
+
+pi-profile-switch seeds the global `profiles/` directory with a starter **`ask`** profile (`ask.json`) — best-effort on install, and guaranteed in place at every launcher startup — read-only Q&A and code exploration. It assumes nothing about your setup; edit or delete it freely:
 
 ```json
 {

package/README.zh-CN.md

@@ -18,7 +18,7 @@ npm install -g pi-profile-switch
 # 使用内建 default profile 启动（全量资源，等同原生 Pi）
 pi-profile
 
-# 使用安装时播种的只读 ask profile 启动
+# 使用 starter 只读 ask profile 启动
 pi-profile ask
 
 # -- 后面的参数原样传给 pi
@@ -36,7 +36,9 @@ profile 保存在两个目录中，每个 profile 对应一个独立 JSON 文件
 
 直接编辑或新建 `<name>.json` 即可创建或修改 profile——schema 见 [`schemas/profiles.schema.json`](schemas/profiles.schema.json)。
 
-安装时，pi-profile-switch 会向全局 `profiles/` 目录播种一个初始 **`ask`** profile（`ask.json`）——只读的问答与代码走读模式。它不假设你安装过任何插件，可随意修改或删除：
+你也可以通过对话让 agent 帮你配置：随包附带的 **`profile-config`** skill（安装时 best-effort 分发、launcher 启动时保证就位，位于 `<agentDir>/skills/profile-config/`）会指导 agent 澄清需求、发现资源并读写 profile 文件。按约定，生成声明了 `skills` 的 profile 时默认包含 `"profile-config"`（除非明确排除或已被 `*` 等 glob 覆盖），确保切换到新 profile 后仍可持续对话配置。详情见 [`skills/profile-config/SKILL.md`](skills/profile-config/SKILL.md)。
+
+pi-profile-switch 会向全局 `profiles/` 目录播种一个初始 **`ask`** profile（`ask.json`）——安装时 best-effort、launcher 启动时保证就位——它是只读的问答与代码走读模式。它不假设你安装过任何插件，可随意修改或删除：
 
 ```json
 {

package/bin/pi-profile.ts

@@ -21,11 +21,20 @@ import { spawnPi } from "../src/launcher/spawn.ts";
 import { McpConfigError, MissingMcpAdapterError } from "../src/mcp-config.ts";
 import { CatalogError } from "../src/profile-catalog.ts";
 import { ActivationError } from "../src/profile-resolver.ts";
+import { ensureStarterAssets } from "../src/starter-assets.ts";
 import { generateRuntimeDir } from "../src/settings-generator.ts";
 
 try {
 	const args = parseLauncherArgs(process.argv.slice(2));
 	const agentDir = getAgentDir();
+	// Starter assets (seed profile + profile-config skill) are ensured before
+	// initial profile resolution so the seed is visible to this launch's
+	// resolution and /profile list. Best-effort: ensure failures never block
+	// the launch (same pattern as the sweep below).
+	const starterAssets = await ensureStarterAssets({ agentDir });
+	for (const warning of starterAssets.warnings) {
+		console.error(`pi-profile: warning: ${warning}`);
+	}
 	// Fails before spawning when the profile is unknown or cannot activate.
 	// --approve/--no-approve are consumed here as a one-run trust input.
 	const { plan, discovery, projectDir, warnings } = await resolveInitialProfile(args.profile, {

package/bin/postinstall.d.ts

@@ -11,3 +11,5 @@ export interface InstallResult {
 }
 
 export function installDefaultProfiles(options?: { env?: NodeJS.ProcessEnv }): Promise<InstallResult>;
+
+export function installProfileConfigSkill(options?: { env?: NodeJS.ProcessEnv }): Promise<InstallResult>;

package/bin/postinstall.js

@@ -1,17 +1,34 @@
 #!/usr/bin/env node
 /**
- * postinstall: seed the global catalog with the default starter profile.
+ * postinstall: best-effort early seeding of the global catalog with the
+ * default starter profile, and distribution of the profile-config skill to
+ * the agent skills directory.
  *
  * Runs at package install time (`npm install pi-profile-switch` / `pi install`).
+ *
+ * Role: this hook is an early optimization, NOT the sole distribution
+ * channel. npm v12+ blocks dependency lifecycle scripts by default
+ * (allowScripts), so installs that skip this hook are covered by the
+ * launcher instead: `bin/pi-profile.ts` calls the runtime ensure
+ * (src/starter-assets.ts) on every launch, before resolving the initial
+ * profile. The authoritative behavior contract for both assets lives in
+ * openspec/specs/profile-catalog/spec.md ("播种 starter profile" and
+ * "分发 profile-config skill"); keep this script's rules in sync with
+ * src/starter-assets.ts, which is the single TS implementation.
+ *
  * Idempotent and conservative:
  * - Writes the shipped `examples/ask.json` starter profile to the
  *   profiles dir ONLY when no .json profile exists there yet
  *   (COPYFILE_EXCL; an existing file — including one written concurrently — is never touched).
+ * - Distributes the shipped `skills/profile-config/SKILL.md` to
+ *   `<agentDir>/skills/profile-config/SKILL.md`, always overwriting with
+ *   the shipped version so the skill stays in sync with the package.
  * - Never fails the install: errors are downgraded to a warning.
  *
  * This module is plain Node ESM (no jiti/TS): npm may run postinstall in a
  * context where only plain JS is safe. The path rules intentionally mirror
- * src/workspace.ts — keep them in sync.
+ * src/workspace.ts and Pi's getAgentDir() (in @earendil-works/pi-coding-agent)
+ * — keep them in sync.
  */
 import { copyFile, mkdir, readdir } from "node:fs/promises";
 import { constants } from "node:fs";
@@ -20,6 +37,7 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 const DEFAULT_TEMPLATE = fileURLToPath(new URL("../examples/ask.json", import.meta.url));
+const SKILL_TEMPLATE = fileURLToPath(new URL("../skills/profile-config/SKILL.md", import.meta.url));
 
 /** Mirrors getProfileSwitchDir() in src/workspace.ts.
  *  @param {NodeJS.ProcessEnv} env */
@@ -35,6 +53,24 @@ function globalProfilesDir(env) {
 	return path.join(profileSwitchDir(env), "profiles");
 }
 
+/** Mirrors Pi's getAgentDir() in @earendil-works/pi-coding-agent.
+ *  Keep in sync with Pi's config resolution.
+ *  Deliberate divergence from Pi: trims whitespace and resolves relative
+ *  paths via path.resolve() for safety during postinstall.
+ *  @param {NodeJS.ProcessEnv} env */
+function agentDir(env) {
+	const override = env.PI_CODING_AGENT_DIR;
+	if (override && override.trim()) {
+		const trimmed = override.trim();
+		if (trimmed === "~") return homedir();
+		if (trimmed.startsWith("~/") || (process.platform === "win32" && trimmed.startsWith("~\\"))) {
+			return path.join(homedir(), trimmed.slice(2));
+		}
+		return path.resolve(trimmed);
+	}
+	return path.join(homedir(), ".pi", "agent");
+}
+
 /** Checks whether the directory exists and contains any .json files.
  *  @param {string} dir */
 async function hasAnyJsonProfiles(dir) {
@@ -74,6 +110,28 @@ export async function installDefaultProfiles({ env = process.env } = {}) {
 	return { path: target, written: true };
 }
 
+/**
+ * Distributes the shipped profile-config skill to the agent skills directory.
+ * Always overwrites with the shipped version. Downgrades failures to a warning.
+ * @param {{ env?: NodeJS.ProcessEnv }} [options]
+ * @returns {Promise<InstallResult>}
+ */
+export async function installProfileConfigSkill({ env = process.env } = {}) {
+	const dir = path.join(agentDir(env), "skills", "profile-config");
+	const target = path.join(dir, "SKILL.md");
+
+	try {
+		await mkdir(dir, { recursive: true });
+		await copyFile(SKILL_TEMPLATE, target);
+		return { path: target, written: true };
+	} catch (error) {
+		console.warn(
+			`pi-profile: could not distribute profile-config skill: ${error instanceof Error ? error.message : error}`,
+		);
+		return { path: target, written: false };
+	}
+}
+
 const invokedDirectly = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
 if (invokedDirectly) {
 	installDefaultProfiles().then(
@@ -84,4 +142,12 @@ if (invokedDirectly) {
 			console.warn(`pi-profile: could not seed starter profile: ${error instanceof Error ? error.message : error}`);
 		},
 	);
+	installProfileConfigSkill().then(
+		(result) => {
+			if (result.written) console.log(`pi-profile: distributed profile-config skill at ${result.path}`);
+		},
+		(error) => {
+			console.warn(`pi-profile: could not distribute profile-config skill: ${error instanceof Error ? error.message : error}`);
+		},
+	);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-profile-switch",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Named profiles for Pi: reference skills, extensions, MCP servers, and tools per workflow, switched without restarting. Install: npm install -g pi-profile-switch (not pi install).",
   "type": "module",
   "keywords": [
@@ -46,6 +46,7 @@
   "files": [
     "bin",
     "extensions",
+    "skills",
     "src",
     "schemas",
     "examples",

package/skills/profile-config/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: profile-config
+description: 指导创建、修改或删除 pi-profile-switch 的 profile。当用户想要创建、修改、配置或删除 profile 时触发。
+---
+
+# profile-config
+
+本 skill 指导 agent 理解用户的模糊需求或明确指令，协助用户创建、修改或删除 `pi-profile-switch` 的 profile 文件。
+
+> **声明**：本 skill 文件由 `pi-profile-switch` package 安装分发并在随包升级时自动覆写，请勿手动修改此文件。
+
+---
+
+## 1. 核心概念与约束
+
+### 1.1 Profile 与 Catalog
+- **Profile**：命名的能力定义，引用 skills、extensions、MCP servers 与 tools，可选声明 model、thinking level 与 instructions。
+- **Catalog**：保存 profile 定义的 `profiles/` 目录。每个 profile 对应目录下的一个独立 JSON 文件：`<name>.json`。
+- **default profile**：由 Pi 提供，不可删除、不可编辑的 profile，加载 Pi 可发现的全部资源。**严禁**在任何 profiles 目录下创建 `default.json`。
+
+### 1.2 名字字符集规范
+Profile 名字必须完全匹配正则：
+```regex
+^[A-Za-z0-9][A-Za-z0-9._-]*$
+```
+- 必须以英文字母或数字开头。
+- 只允许英文字母、数字、点（`.`）、下划线（`_`）和连字符（`-`）。
+- 不允许包含空格、中文或特殊符号。
+
+### 1.3 作用域（Source scope）与存储落点
+Profile 文件存放在两个位置之一：
+
+| 作用域 | 路径 | 说明 |
+| --- | --- | --- |
+| **全局（global）** | `$PI_PROFILE_SWITCH_DIR/profiles/<name>.json`<br>（缺省为 `~/.pi-profile-switch/profiles/<name>.json`） | 对所有项目通用。若环境变量 `PI_PROFILE_SWITCH_DIR` 存在且非空，则以其下的 `profiles/` 目录为准。 |
+| **项目（project）** | `<projectDir>/.pi/profiles/<name>.json` | 仅在当前项目生效，且仅当项目已受信任时可用。 |
+
+- **覆盖规则**：项目 scope 的同名 profile 会完整替换（replace）全局条目，**不会**与全局配置合并字段。
+- **项目信任门禁**：若当前项目未受信任，项目 scope 的 profile 无法解析，向项目 scope 写入也会失败。写入项目 scope 前若项目未受信任，必须提示用户在会话中执行 `/trust` 并重启 Pi。
+
+---
+
+## 2. Profile 文件格式与字段定义
+
+文件内容必须为格式化 JSON，**顶层即为裸定义对象**，严禁包裹 `schemaVersion`、`profiles` 或其他外层信封字段。
+
+全部字段均为可选（optional）。未声明的字段保持原生 Pi 行为或当前状态，不产生任何副作用。
+
+### 字段详细语义
+
+| 字段 | 类型 | 语义与约束 |
+| --- | --- | --- |
+| `label` | `string` | 人类可读的显示名称（如 `"Code Review"`）。 |
+| `description` | `string` | Profile 的简要描述（如 `"Read-only review profile"`）。 |
+| `skills` | `string[]` | 引用的 skill 名称或 glob 列表。未声明时不收窄可用 skills。 |
+| `extensions` | `string[]` | 引用的 extension 标识或 glob 列表。未声明时不收窄可用 extensions。 |
+| `mcps` | `string[]` | 引用的 MCP server 名称或 glob 列表。未声明时不依赖 `pi-mcp-adapter`。 |
+| `tools` | `string[]` | 白名单工具名称或 glob 列表。未声明时不收窄工具，保持 Pi 原生工具集合。 |
+| `defaultProvider` | `string` | 默认模型提供商（如 `"anthropic"`、`"openai"`）。与 `defaultModel` 必须同时声明才生效。 |
+| `defaultModel` | `string` | 默认模型名称（如 `"claude-sonnet-4-5"`）。与 `defaultProvider` 必须同时声明才生效。 |
+| `defaultThinkingLevel` | `string` | 默认思考等级，可选值：`"off"`、`"minimal"`、`"low"`、`"medium"`、`"high"`、`"xhigh"`、`"max"`。仅在模型声明成立时生效。 |
+| `instructions` | `string` | 激活该 profile 时追加到系统提示词的指令文本。 |
+
+### 示例格式
+```json
+{
+  "label": "Review Mode",
+  "description": "Read-only code review with linting and analysis tools",
+  "skills": [
+    "profile-config"
+  ],
+  "extensions": [],
+  "mcps": [],
+  "tools": [
+    "read",
+    "grep",
+    "find",
+    "ls"
+  ],
+  "defaultProvider": "anthropic",
+  "defaultModel": "claude-sonnet-4-5",
+  "defaultThinkingLevel": "high",
+  "instructions": "Focus on code quality, security, and edge cases. Do not edit files."
+}
+```
+
+---
+
+## 3. 可引用资源发现指引
+
+当帮助用户配置 profile 时，可检查或参考以下位置发现用户当前已有的可用资源：
+
+1. **Skills**：
+   - 发现位置：`<agentDir>/skills/` 以及全局 `~/.agents/skills/`。
+   - 引用身份：Pi 的 skill 名称（即 skill 目录下的 `SKILL.md` frontmatter 中声明的 `name`，或目录名）。
+   - 支持 glob（如 `"git-*"`）。
+2. **Extensions**：
+   - 发现位置：`<agentDir>/settings.json` 中声明的已安装 packages、`<agentDir>/extensions/` 下的散装文件（`.ts` 或 `.js`）。
+   - 引用形式：
+     - 已安装包的包名或 source 别名。
+     - 多入口包的入口 ID：`<包名>:<相对路径>`。
+     - 散装文件 ID：相对扩展目录的路径去掉 `.ts`/`.js`（如 `sub/index.ts` 引用为 `sub`）。
+     - 绝对路径或 `~/` 路径。
+     - glob 匹配。
+3. **MCP Servers**：
+   - 发现位置：`pi-mcp-adapter` 识别的标准配置位置——全局侧 `~/.config/mcp/mcp.json`、`~/.agents/mcp.json`、`~/.agents/mcp/mcp.json`、`<agentDir>/mcp.json`；受信任项目另有 `<projectDir>/.mcp.json` 与 `<projectDir>/.pi/mcp.json`。
+   - 引用身份：上述配置文件中 `mcpServers` 对象下的 server 键名。
+   - 声明了 `mcps` 的 profile 需要同时确保 `pi-mcp-adapter` extension 处于可用状态。
+4. **Tools**：
+   - 引用身份：Pi 实时工具注册表中的工具名。
+   - 包括内建工具（`read`、`write`、`edit`、`bash` 等）、extension 贡献的工具、以及 MCP server 暴露的工具（代理工具 `mcp__<server>` 与直接工具 `<server>_<tool>`）。
+   - 支持 glob（如 `"mcp__*"`、`"github_*"`）。
+5. **项目级资源的收窄边界（重要）**：
+   - Profile 的资源选择（`skills`、`extensions`）**仅作用于用户级资源**（真实 agentDir 与 `~/.agents/skills`）。
+   - 项目级资源（如项目 `.pi/skills`、项目 `.pi/extensions`、上级 `.agents/skills`）的可见性由 Pi 项目信任判定决定：在受信任项目中，它们在**任何** profile 下都始终可见；在未受信任项目中均不可见。
+   - 因此，项目级资源的可见性**不随 profile 收窄**，无需也不指导在 profile 中声明项目级资源。
+
+---
+
+## 4. 创作时的默认注入规则
+
+当为用户创建或生成声明了 `skills` 的新 profile 时，必须遵守以下约定：
+
+1. **默认注入 `"profile-config"`**：
+   - 若生成的 profile 声明了 `skills` 数组，默认在 `skills` 列表中包含 `"profile-config"`，以保证切入该 profile 后用户仍可继续通过本 skill 配置 profile。
+   - **例外 1**：用户明确要求不包含 `"profile-config"` 时除外。
+   - **例外 2**：若 `skills` 列表中已包含具有覆盖性的 glob（例如 `"*"`），则无需重复显式添加 `"profile-config"`。
+2. **未声明 `skills` 时不动作**：
+   - 若 profile 未声明 `skills` 字段，表示不收窄 skills，全部 skill（包括 `profile-config`）天然可用，因此绝对不要主动添加 `skills` 字段。
+
+---
+
+## 5. 交互与执行流程
+
+### 5.1 创建（Create）
+1. **需求澄清**：根据用户自然语言描述（如「帮我配一个用于安全审计的只读 profile」），明确：
+   - 目标名称（校验符合 `^[A-Za-z0-9][A-Za-z0-9._-]*$`，且非 `default`）。
+   - 目标 scope（全局还是项目级）。
+   - 需要收窄的工具、skills、extensions、MCP servers 或特定模型设定。
+2. **资源与环境核对**：根据上述规则构造合法 JSON 定义，应用创作时默认注入规则。
+3. **写入文件**：
+   - 全局路径：`$PI_PROFILE_SWITCH_DIR/profiles/<name>.json`（默认 `~/.pi-profile-switch/profiles/<name>.json`）。
+   - 项目路径：`<projectDir>/.pi/profiles/<name>.json`。
+   - 确保目录存在，写入格式化的 JSON。
+4. **提示用户生效**：告知用户可通过 `/profile reload` 或 `/profile use <name>` 立即使用新 profile。
+
+### 5.2 修改（Edit）
+1. 读取目标 profile 文件已有内容。
+2. 根据用户要求调整对应字段，保持其余字段完整。
+3. 校验并写回格式化 JSON。
+4. 提示用户执行 `/profile reload`。
+
+### 5.3 删除（Delete）
+1. 确认要删除的 profile 存在于指定 scope。
+2. 严禁尝试删除 `default` profile。
+3. 删除对应的 `<name>.json` 文件。若当前正在使用该 profile，提醒用户先切换到其他 profile（如 `/profile use default`）。
+
+---
+
+## 6. 边界与退化处理
+
+1. **只读 / 无 `write` 工具环境**：
+   - 如果当前会话处于收窄工具的 profile 中（例如没有 `write` 工具的只读模式）：
+   - 退化为在回复中输出完整的格式化 JSON 内容与建议保存的文件绝对路径，建议用户手动保存或切换至具备文件写入能力的 profile（如 `/profile use default`）后再行保存。
+2. **未受信任项目**：
+   - 如果需要写入项目 scope（`<projectDir>/.pi/profiles/`），而当前项目尚未受信任：
+   - 必须向用户说明项目未受信任无法生效，提示用户执行 `/trust` 并重启 Pi，或改将 profile 保存至全局 scope。

package/src/starter-assets.ts

@@ -0,0 +1,132 @@
+/**
+ * Runtime ensure of starter assets: seeds the starter profile into global
+ * profiles/ if no profile exists yet, and distributes/syncs the profile-config
+ * skill into the user's agent skills directory.
+ *
+ * Idempotent, safe against concurrent launches, and downgrades IO errors
+ * to warnings without throwing.
+ */
+
+import { constants } from "node:fs";
+import { copyFile, mkdir, readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+import { getGlobalProfilesDir } from "./workspace.ts";
+
+export interface StarterAssetFileResult {
+	/** 目标文件绝对路径 */
+	path: string;
+	/** 本次调用是否发生了写入 */
+	written: boolean;
+}
+
+export interface StarterAssetsResult {
+	profile: StarterAssetFileResult;
+	skill: StarterAssetFileResult;
+	/** 人类可读的降级警告；为空表示全部成功或无操作 */
+	warnings: string[];
+}
+
+export interface EnsureStarterAssetsOptions {
+	/** 默认 getGlobalProfilesDir()；测试注入 */
+	globalProfilesDir?: string;
+	/** 默认 Pi 的 getAgentDir()；测试注入 */
+	agentDir?: string;
+	/** 默认由 import.meta.url 定位包根；测试注入 */
+	packageRoot?: string;
+}
+
+async function hasAnyJsonProfiles(dir: string): Promise<boolean> {
+	try {
+		const entries = await readdir(dir);
+		return entries.some((name) => name.endsWith(".json"));
+	} catch (error: unknown) {
+		const err = error as NodeJS.ErrnoException;
+		if (err.code === "ENOENT") {
+			return false;
+		}
+		throw error;
+	}
+}
+
+export async function ensureStarterAssets(options?: EnsureStarterAssetsOptions): Promise<StarterAssetsResult> {
+	const defaultPackageRoot = fileURLToPath(new URL("..", import.meta.url));
+	const packageRoot = options?.packageRoot ? path.resolve(options.packageRoot) : defaultPackageRoot;
+	const globalProfiles = options?.globalProfilesDir ? path.resolve(options.globalProfilesDir) : getGlobalProfilesDir();
+	const agent = options?.agentDir ? path.resolve(options.agentDir) : getAgentDir();
+
+	const profileTemplate = path.join(packageRoot, "examples", "ask.json");
+	const targetProfilePath = path.join(globalProfiles, "ask.json");
+
+	const skillTemplate = path.join(packageRoot, "skills", "profile-config", "SKILL.md");
+	const targetSkillDir = path.join(agent, "skills", "profile-config");
+	const targetSkillPath = path.join(targetSkillDir, "SKILL.md");
+
+	const warnings: string[] = [];
+	const profileResult: StarterAssetFileResult = {
+		path: targetProfilePath,
+		written: false,
+	};
+	const skillResult: StarterAssetFileResult = {
+		path: targetSkillPath,
+		written: false,
+	};
+
+	// 1. Starter profile seeding
+	try {
+		const hasJson = await hasAnyJsonProfiles(globalProfiles);
+		if (!hasJson) {
+			await mkdir(globalProfiles, { recursive: true });
+			try {
+				await copyFile(profileTemplate, targetProfilePath, constants.COPYFILE_EXCL);
+				profileResult.written = true;
+			} catch (error: unknown) {
+				const err = error as NodeJS.ErrnoException;
+				if (err.code === "EEXIST") {
+					// Lost a create race (concurrent launch); winner stands
+					profileResult.written = false;
+				} else {
+					throw error;
+				}
+			}
+		}
+	} catch (error: unknown) {
+		const message = error instanceof Error ? error.message : String(error);
+		warnings.push(`could not seed starter profile: ${message}`);
+	}
+
+	// 2. Profile-config skill distribution & sync
+	try {
+		const templateContent = await readFile(skillTemplate, "utf8");
+		let needsWrite = true;
+		try {
+			const existingContent = await readFile(targetSkillPath, "utf8");
+			if (existingContent === templateContent) {
+				needsWrite = false;
+			}
+		} catch (error: unknown) {
+			const err = error as NodeJS.ErrnoException;
+			if (err.code !== "ENOENT") {
+				throw error;
+			}
+		}
+
+		if (needsWrite) {
+			await mkdir(targetSkillDir, { recursive: true });
+			await copyFile(skillTemplate, targetSkillPath);
+			skillResult.written = true;
+		}
+	} catch (error: unknown) {
+		const message = error instanceof Error ? error.message : String(error);
+		warnings.push(`could not distribute profile-config skill: ${message}`);
+	}
+
+	return {
+		profile: profileResult,
+		skill: skillResult,
+		warnings,
+	};
+}