rulesync 3.28.1 → 3.29.0

package/README.md

@@ -213,11 +213,28 @@ npx rulesync gitignore
 
 You can configure Rulesync by creating a `rulesync.jsonc` file in the root of your project.
 
+### JSON Schema Support
+
+Rulesync provides a JSON Schema for editor validation and autocompletion. Add the `$schema` property to your `rulesync.jsonc`:
+
+```jsonc
+// rulesync.jsonc
+{
+  "$schema": "https://raw.githubusercontent.com/dyoshikawa/rulesync/refs/heads/main/config-schema.json",
+  "targets": ["claudecode"],
+  "features": ["rules"]
+}
+```
+
+### Configuration Options
+
 Example:
 
 ```jsonc
 // rulesync.jsonc
 {
+  "$schema": "https://raw.githubusercontent.com/dyoshikawa/rulesync/refs/heads/main/config-schema.json",
+
   // List of tools to generate configurations for. You can specify "*" to generate all tools.
   "targets": ["cursor", "claudecode", "geminicli", "opencode", "codexcli"],
 
@@ -670,6 +687,16 @@ The Rulesync MCP server provides the following tools:
 
 </details>
 
+<details>
+<summary>Skills Management</summary>
+
+- `listSkills` - List all skill directories
+- `getSkill` - Get a specific skill (SKILL.md and other files)
+- `putSkill` - Create or update a skill directory
+- `deleteSkill` - Delete a skill directory
+
+</details>
+
 <details>
 <summary>Ignore Files Management</summary>
 

package/dist/index.cjs

@@ -290,6 +290,10 @@ var ConfigParamsSchema = import_mini3.z.object({
   experimentalSimulateSubagents: (0, import_mini3.optional)(import_mini3.z.boolean())
 });
 var PartialConfigParamsSchema = import_mini3.z.partial(ConfigParamsSchema);
+var ConfigFileSchema = import_mini3.z.object({
+  $schema: (0, import_mini3.optional)(import_mini3.z.string()),
+  ...import_mini3.z.partial(ConfigParamsSchema).shape
+});
 var RequiredConfigParamsSchema = import_mini3.z.required(ConfigParamsSchema);
 var Config = class {
   baseDirs;
@@ -419,7 +423,9 @@ var ConfigResolver = class {
       try {
         const fileContent = await readFileContent(validatedConfigPath);
         const jsonData = (0, import_jsonc_parser.parse)(fileContent);
-        configByFile = PartialConfigParamsSchema.parse(jsonData);
+        const parsed = ConfigFileSchema.parse(jsonData);
+        const { $schema: _schema, ...configParams2 } = parsed;
+        configByFile = configParams2;
       } catch (error) {
         logger.error(`Failed to load config file: ${formatError(error)}`);
         throw error;
@@ -665,6 +671,13 @@ var AiFile = class {
   setFileContent(newFileContent) {
     this.fileContent = newFileContent;
   }
+  /**
+   * Returns whether this file can be deleted by rulesync.
+   * Override in subclasses that should not be deleted (e.g., user-managed config files).
+   */
+  isDeletable() {
+    return true;
+  }
 };
 
 // src/features/commands/tool-command.ts
@@ -2324,6 +2337,13 @@ var ClaudecodeIgnore = class _ClaudecodeIgnore extends ToolIgnore {
       relativeFilePath: "settings.local.json"
     };
   }
+  /**
+   * ClaudecodeIgnore uses settings.local.json which is a user-managed config file.
+   * It should not be deleted by rulesync.
+   */
+  isDeletable() {
+    return false;
+  }
   toRulesyncIgnore() {
     const rulesyncPatterns = this.patterns.map((pattern) => {
       if (pattern.startsWith("Read(") && pattern.endsWith(")")) {
@@ -2814,7 +2834,7 @@ var IgnoreProcessor = class extends FeatureProcessor {
     try {
       const toolIgnores = await this.loadToolIgnores();
       if (forDeletion) {
-        return toolIgnores.filter((toolFile) => !(toolFile instanceof ClaudecodeIgnore));
+        return toolIgnores.filter((toolFile) => toolFile.isDeletable());
       }
       return toolIgnores;
     } catch (error) {
@@ -3316,6 +3336,14 @@ var ClaudecodeMcp = class _ClaudecodeMcp extends ToolMcp {
   getJson() {
     return this.json;
   }
+  /**
+   * In global mode, ~/.claude/.claude.json should not be deleted
+   * as it may contain other user settings.
+   * In local mode, .mcp.json can be safely deleted.
+   */
+  isDeletable() {
+    return !this.global;
+  }
   static getSettablePaths({ global } = {}) {
     if (global) {
       return {
@@ -3898,6 +3926,12 @@ var OpencodeMcp = class _OpencodeMcp extends ToolMcp {
   getJson() {
     return this.json;
   }
+  /**
+   * opencode.json may contain other settings, so it should not be deleted.
+   */
+  isDeletable() {
+    return false;
+  }
   static getSettablePaths({ global } = {}) {
     if (global) {
       return {
@@ -4182,11 +4216,7 @@ var McpProcessor = class extends FeatureProcessor {
       })();
       logger.info(`Successfully loaded ${toolMcps.length} ${this.toolTarget} MCP files`);
       if (forDeletion) {
-        let filteredMcps = toolMcps.filter((toolFile) => !(toolFile instanceof OpencodeMcp));
-        if (this.global) {
-          filteredMcps = filteredMcps.filter((toolFile) => !(toolFile instanceof ClaudecodeMcp));
-        }
-        return filteredMcps;
+        return toolMcps.filter((toolFile) => toolFile.isDeletable());
       }
       return toolMcps;
     } catch (error) {
@@ -4567,20 +4597,13 @@ var SimulatedSkill = class extends ToolSkill {
       name: rulesyncFrontmatter.name,
       description: rulesyncFrontmatter.description
     };
-    const otherFiles = rulesyncSkill.getOtherFiles();
-    if (otherFiles.length > 0) {
-      logger.warn(
-        `Skill "${rulesyncFrontmatter.name}" has ${otherFiles.length} additional file(s) that will be ignored for simulated skill generation.`
-      );
-    }
     return {
       baseDir: rulesyncSkill.getBaseDir(),
       relativeDirPath: this.getSettablePaths().relativeDirPath,
       dirName: rulesyncSkill.getDirName(),
       frontmatter: simulatedFrontmatter,
       body: rulesyncSkill.getBody(),
-      otherFiles: [],
-      // Simulated skills ignore otherFiles
+      otherFiles: rulesyncSkill.getOtherFiles(),
       validate
     };
   }
@@ -4602,14 +4625,19 @@ var SimulatedSkill = class extends ToolSkill {
     if (!result.success) {
       throw new Error(`Invalid frontmatter in ${skillFilePath}: ${formatError(result.error)}`);
     }
+    const otherFiles = await this.collectOtherFiles(
+      baseDir,
+      actualRelativeDirPath,
+      dirName,
+      SKILL_FILE_NAME
+    );
     return {
       baseDir,
       relativeDirPath: actualRelativeDirPath,
       dirName,
       frontmatter: result.data,
       body: content.trim(),
-      otherFiles: [],
-      // Simulated skills ignore otherFiles
+      otherFiles,
       validate: true
     };
   }
@@ -10024,13 +10052,247 @@ var ruleTools = {
   }
 };
 
-// src/mcp/subagents.ts
+// src/mcp/skills.ts
 var import_node_path88 = require("path");
 var import_mini35 = require("zod/mini");
+var maxSkillSizeBytes = 1024 * 1024;
+var maxSkillsCount = 1e3;
+function aiDirFileToMcpSkillFile(file) {
+  return {
+    name: file.relativeFilePathToDirPath,
+    body: file.fileBuffer.toString("utf-8")
+  };
+}
+function mcpSkillFileToAiDirFile(file) {
+  return {
+    relativeFilePathToDirPath: file.name,
+    fileBuffer: Buffer.from(file.body, "utf-8")
+  };
+}
+function extractDirName(relativeDirPathFromCwd) {
+  const dirName = (0, import_node_path88.basename)(relativeDirPathFromCwd);
+  if (!dirName) {
+    throw new Error(`Invalid path: ${relativeDirPathFromCwd}`);
+  }
+  return dirName;
+}
+async function listSkills() {
+  const skillsDir = (0, import_node_path88.join)(process.cwd(), RULESYNC_SKILLS_RELATIVE_DIR_PATH);
+  try {
+    const skillDirPaths = await findFilesByGlobs((0, import_node_path88.join)(skillsDir, "*"), { type: "dir" });
+    const skills = await Promise.all(
+      skillDirPaths.map(async (dirPath) => {
+        const dirName = (0, import_node_path88.basename)(dirPath);
+        if (!dirName) return null;
+        try {
+          const skill = await RulesyncSkill.fromDir({
+            dirName
+          });
+          const frontmatter = skill.getFrontmatter();
+          return {
+            relativeDirPathFromCwd: (0, import_node_path88.join)(RULESYNC_SKILLS_RELATIVE_DIR_PATH, dirName),
+            frontmatter
+          };
+        } catch (error) {
+          logger.error(`Failed to read skill directory ${dirName}: ${formatError(error)}`);
+          return null;
+        }
+      })
+    );
+    return skills.filter((skill) => skill !== null);
+  } catch (error) {
+    logger.error(`Failed to read skills directory: ${formatError(error)}`);
+    return [];
+  }
+}
+async function getSkill({ relativeDirPathFromCwd }) {
+  checkPathTraversal({
+    relativePath: relativeDirPathFromCwd,
+    intendedRootDir: process.cwd()
+  });
+  const dirName = extractDirName(relativeDirPathFromCwd);
+  try {
+    const skill = await RulesyncSkill.fromDir({
+      dirName
+    });
+    return {
+      relativeDirPathFromCwd: (0, import_node_path88.join)(RULESYNC_SKILLS_RELATIVE_DIR_PATH, dirName),
+      frontmatter: skill.getFrontmatter(),
+      body: skill.getBody(),
+      otherFiles: skill.getOtherFiles().map(aiDirFileToMcpSkillFile)
+    };
+  } catch (error) {
+    throw new Error(
+      `Failed to read skill directory ${relativeDirPathFromCwd}: ${formatError(error)}`,
+      {
+        cause: error
+      }
+    );
+  }
+}
+async function putSkill({
+  relativeDirPathFromCwd,
+  frontmatter,
+  body,
+  otherFiles = []
+}) {
+  checkPathTraversal({
+    relativePath: relativeDirPathFromCwd,
+    intendedRootDir: process.cwd()
+  });
+  const dirName = extractDirName(relativeDirPathFromCwd);
+  const estimatedSize = JSON.stringify(frontmatter).length + body.length + otherFiles.reduce((acc, file) => acc + file.name.length + file.body.length, 0);
+  if (estimatedSize > maxSkillSizeBytes) {
+    throw new Error(
+      `Skill size ${estimatedSize} bytes exceeds maximum ${maxSkillSizeBytes} bytes (1MB)`
+    );
+  }
+  try {
+    const existingSkills = await listSkills();
+    const isUpdate = existingSkills.some(
+      (skill2) => skill2.relativeDirPathFromCwd === (0, import_node_path88.join)(RULESYNC_SKILLS_RELATIVE_DIR_PATH, dirName)
+    );
+    if (!isUpdate && existingSkills.length >= maxSkillsCount) {
+      throw new Error(`Maximum number of skills (${maxSkillsCount}) reached`);
+    }
+    const aiDirFiles = otherFiles.map(mcpSkillFileToAiDirFile);
+    const skill = new RulesyncSkill({
+      baseDir: process.cwd(),
+      relativeDirPath: RULESYNC_SKILLS_RELATIVE_DIR_PATH,
+      dirName,
+      frontmatter,
+      body,
+      otherFiles: aiDirFiles,
+      validate: true
+    });
+    const skillDirPath = (0, import_node_path88.join)(process.cwd(), RULESYNC_SKILLS_RELATIVE_DIR_PATH, dirName);
+    await ensureDir(skillDirPath);
+    const skillFilePath = (0, import_node_path88.join)(skillDirPath, SKILL_FILE_NAME);
+    const skillFileContent = stringifyFrontmatter(body, frontmatter);
+    await writeFileContent(skillFilePath, skillFileContent);
+    for (const file of otherFiles) {
+      checkPathTraversal({
+        relativePath: file.name,
+        intendedRootDir: skillDirPath
+      });
+      const filePath = (0, import_node_path88.join)(skillDirPath, file.name);
+      const fileDir = (0, import_node_path88.join)(skillDirPath, (0, import_node_path88.dirname)(file.name));
+      if (fileDir !== skillDirPath) {
+        await ensureDir(fileDir);
+      }
+      await writeFileContent(filePath, file.body);
+    }
+    return {
+      relativeDirPathFromCwd: (0, import_node_path88.join)(RULESYNC_SKILLS_RELATIVE_DIR_PATH, dirName),
+      frontmatter: skill.getFrontmatter(),
+      body: skill.getBody(),
+      otherFiles: skill.getOtherFiles().map(aiDirFileToMcpSkillFile)
+    };
+  } catch (error) {
+    throw new Error(
+      `Failed to write skill directory ${relativeDirPathFromCwd}: ${formatError(error)}`,
+      {
+        cause: error
+      }
+    );
+  }
+}
+async function deleteSkill({
+  relativeDirPathFromCwd
+}) {
+  checkPathTraversal({
+    relativePath: relativeDirPathFromCwd,
+    intendedRootDir: process.cwd()
+  });
+  const dirName = extractDirName(relativeDirPathFromCwd);
+  const skillDirPath = (0, import_node_path88.join)(process.cwd(), RULESYNC_SKILLS_RELATIVE_DIR_PATH, dirName);
+  try {
+    if (await directoryExists(skillDirPath)) {
+      await removeDirectory(skillDirPath);
+    }
+    return {
+      relativeDirPathFromCwd: (0, import_node_path88.join)(RULESYNC_SKILLS_RELATIVE_DIR_PATH, dirName)
+    };
+  } catch (error) {
+    throw new Error(
+      `Failed to delete skill directory ${relativeDirPathFromCwd}: ${formatError(error)}`,
+      {
+        cause: error
+      }
+    );
+  }
+}
+var McpSkillFileSchema = import_mini35.z.object({
+  name: import_mini35.z.string(),
+  body: import_mini35.z.string()
+});
+var skillToolSchemas = {
+  listSkills: import_mini35.z.object({}),
+  getSkill: import_mini35.z.object({
+    relativeDirPathFromCwd: import_mini35.z.string()
+  }),
+  putSkill: import_mini35.z.object({
+    relativeDirPathFromCwd: import_mini35.z.string(),
+    frontmatter: RulesyncSkillFrontmatterSchema,
+    body: import_mini35.z.string(),
+    otherFiles: import_mini35.z.optional(import_mini35.z.array(McpSkillFileSchema))
+  }),
+  deleteSkill: import_mini35.z.object({
+    relativeDirPathFromCwd: import_mini35.z.string()
+  })
+};
+var skillTools = {
+  listSkills: {
+    name: "listSkills",
+    description: `List all skills from ${(0, import_node_path88.join)(RULESYNC_SKILLS_RELATIVE_DIR_PATH, "*", SKILL_FILE_NAME)} with their frontmatter.`,
+    parameters: skillToolSchemas.listSkills,
+    execute: async () => {
+      const skills = await listSkills();
+      const output = { skills };
+      return JSON.stringify(output, null, 2);
+    }
+  },
+  getSkill: {
+    name: "getSkill",
+    description: "Get detailed information about a specific skill including SKILL.md content and other files. relativeDirPathFromCwd parameter is required.",
+    parameters: skillToolSchemas.getSkill,
+    execute: async (args) => {
+      const result = await getSkill({ relativeDirPathFromCwd: args.relativeDirPathFromCwd });
+      return JSON.stringify(result, null, 2);
+    }
+  },
+  putSkill: {
+    name: "putSkill",
+    description: "Create or update a skill (upsert operation). relativeDirPathFromCwd, frontmatter, and body parameters are required. otherFiles is optional.",
+    parameters: skillToolSchemas.putSkill,
+    execute: async (args) => {
+      const result = await putSkill({
+        relativeDirPathFromCwd: args.relativeDirPathFromCwd,
+        frontmatter: args.frontmatter,
+        body: args.body,
+        otherFiles: args.otherFiles
+      });
+      return JSON.stringify(result, null, 2);
+    }
+  },
+  deleteSkill: {
+    name: "deleteSkill",
+    description: "Delete a skill directory and all its contents. relativeDirPathFromCwd parameter is required.",
+    parameters: skillToolSchemas.deleteSkill,
+    execute: async (args) => {
+      const result = await deleteSkill({ relativeDirPathFromCwd: args.relativeDirPathFromCwd });
+      return JSON.stringify(result, null, 2);
+    }
+  }
+};
+
+// src/mcp/subagents.ts
+var import_node_path89 = require("path");
+var import_mini36 = require("zod/mini");
 var maxSubagentSizeBytes = 1024 * 1024;
 var maxSubagentsCount = 1e3;
 async function listSubagents() {
-  const subagentsDir = (0, import_node_path88.join)(process.cwd(), RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH);
+  const subagentsDir = (0, import_node_path89.join)(process.cwd(), RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH);
   try {
     const files = await listDirectoryFiles(subagentsDir);
     const mdFiles = files.filter((file) => file.endsWith(".md"));
@@ -10043,7 +10305,7 @@ async function listSubagents() {
           });
           const frontmatter = subagent.getFrontmatter();
           return {
-            relativePathFromCwd: (0, import_node_path88.join)(RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, file),
+            relativePathFromCwd: (0, import_node_path89.join)(RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, file),
             frontmatter
           };
         } catch (error) {
@@ -10065,14 +10327,14 @@ async function getSubagent({ relativePathFromCwd }) {
     relativePath: relativePathFromCwd,
     intendedRootDir: process.cwd()
   });
-  const filename = (0, import_node_path88.basename)(relativePathFromCwd);
+  const filename = (0, import_node_path89.basename)(relativePathFromCwd);
   try {
     const subagent = await RulesyncSubagent.fromFile({
       relativeFilePath: filename,
       validate: true
     });
     return {
-      relativePathFromCwd: (0, import_node_path88.join)(RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, filename),
+      relativePathFromCwd: (0, import_node_path89.join)(RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, filename),
       frontmatter: subagent.getFrontmatter(),
       body: subagent.getBody()
     };
@@ -10091,7 +10353,7 @@ async function putSubagent({
     relativePath: relativePathFromCwd,
     intendedRootDir: process.cwd()
   });
-  const filename = (0, import_node_path88.basename)(relativePathFromCwd);
+  const filename = (0, import_node_path89.basename)(relativePathFromCwd);
   const estimatedSize = JSON.stringify(frontmatter).length + body.length;
   if (estimatedSize > maxSubagentSizeBytes) {
     throw new Error(
@@ -10101,7 +10363,7 @@ async function putSubagent({
   try {
     const existingSubagents = await listSubagents();
     const isUpdate = existingSubagents.some(
-      (subagent2) => subagent2.relativePathFromCwd === (0, import_node_path88.join)(RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, filename)
+      (subagent2) => subagent2.relativePathFromCwd === (0, import_node_path89.join)(RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, filename)
     );
     if (!isUpdate && existingSubagents.length >= maxSubagentsCount) {
       throw new Error(`Maximum number of subagents (${maxSubagentsCount}) reached`);
@@ -10114,11 +10376,11 @@ async function putSubagent({
       body,
       validate: true
     });
-    const subagentsDir = (0, import_node_path88.join)(process.cwd(), RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH);
+    const subagentsDir = (0, import_node_path89.join)(process.cwd(), RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH);
     await ensureDir(subagentsDir);
     await writeFileContent(subagent.getFilePath(), subagent.getFileContent());
     return {
-      relativePathFromCwd: (0, import_node_path88.join)(RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, filename),
+      relativePathFromCwd: (0, import_node_path89.join)(RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, filename),
       frontmatter: subagent.getFrontmatter(),
       body: subagent.getBody()
     };
@@ -10133,12 +10395,12 @@ async function deleteSubagent({ relativePathFromCwd }) {
     relativePath: relativePathFromCwd,
     intendedRootDir: process.cwd()
   });
-  const filename = (0, import_node_path88.basename)(relativePathFromCwd);
-  const fullPath = (0, import_node_path88.join)(process.cwd(), RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, filename);
+  const filename = (0, import_node_path89.basename)(relativePathFromCwd);
+  const fullPath = (0, import_node_path89.join)(process.cwd(), RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, filename);
   try {
     await removeFile(fullPath);
     return {
-      relativePathFromCwd: (0, import_node_path88.join)(RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, filename)
+      relativePathFromCwd: (0, import_node_path89.join)(RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, filename)
     };
   } catch (error) {
     throw new Error(
@@ -10150,23 +10412,23 @@ async function deleteSubagent({ relativePathFromCwd }) {
   }
 }
 var subagentToolSchemas = {
-  listSubagents: import_mini35.z.object({}),
-  getSubagent: import_mini35.z.object({
-    relativePathFromCwd: import_mini35.z.string()
+  listSubagents: import_mini36.z.object({}),
+  getSubagent: import_mini36.z.object({
+    relativePathFromCwd: import_mini36.z.string()
   }),
-  putSubagent: import_mini35.z.object({
-    relativePathFromCwd: import_mini35.z.string(),
+  putSubagent: import_mini36.z.object({
+    relativePathFromCwd: import_mini36.z.string(),
     frontmatter: RulesyncSubagentFrontmatterSchema,
-    body: import_mini35.z.string()
+    body: import_mini36.z.string()
   }),
-  deleteSubagent: import_mini35.z.object({
-    relativePathFromCwd: import_mini35.z.string()
+  deleteSubagent: import_mini36.z.object({
+    relativePathFromCwd: import_mini36.z.string()
   })
 };
 var subagentTools = {
   listSubagents: {
     name: "listSubagents",
-    description: `List all subagents from ${(0, import_node_path88.join)(RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, "*.md")} with their frontmatter.`,
+    description: `List all subagents from ${(0, import_node_path89.join)(RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, "*.md")} with their frontmatter.`,
     parameters: subagentToolSchemas.listSubagents,
     execute: async () => {
       const subagents = await listSubagents();
@@ -10213,7 +10475,7 @@ async function mcpCommand({ version }) {
     name: "Rulesync MCP Server",
     // eslint-disable-next-line no-type-assertion/no-type-assertion
     version,
-    instructions: "This server handles Rulesync files including rules, commands, MCP, ignore files, and subagents for any AI agents. It should be used when you need those files."
+    instructions: "This server handles Rulesync files including rules, commands, MCP, ignore files, subagents and skills for any AI agents. It should be used when you need those files."
   });
   server.addTool(ruleTools.listRules);
   server.addTool(ruleTools.getRule);
@@ -10227,6 +10489,10 @@ async function mcpCommand({ version }) {
   server.addTool(subagentTools.getSubagent);
   server.addTool(subagentTools.putSubagent);
   server.addTool(subagentTools.deleteSubagent);
+  server.addTool(skillTools.listSkills);
+  server.addTool(skillTools.getSkill);
+  server.addTool(skillTools.putSkill);
+  server.addTool(skillTools.deleteSkill);
   server.addTool(ignoreTools.getIgnoreFile);
   server.addTool(ignoreTools.putIgnoreFile);
   server.addTool(ignoreTools.deleteIgnoreFile);
@@ -10240,7 +10506,7 @@ async function mcpCommand({ version }) {
 }
 
 // src/cli/index.ts
-var getVersion = () => "3.28.1";
+var getVersion = () => "3.29.0";
 var main = async () => {
   const program = new import_commander.Command();
   const version = getVersion();

package/dist/index.js

@@ -267,6 +267,10 @@ var ConfigParamsSchema = z3.object({
   experimentalSimulateSubagents: optional(z3.boolean())
 });
 var PartialConfigParamsSchema = z3.partial(ConfigParamsSchema);
+var ConfigFileSchema = z3.object({
+  $schema: optional(z3.string()),
+  ...z3.partial(ConfigParamsSchema).shape
+});
 var RequiredConfigParamsSchema = z3.required(ConfigParamsSchema);
 var Config = class {
   baseDirs;
@@ -396,7 +400,9 @@ var ConfigResolver = class {
       try {
         const fileContent = await readFileContent(validatedConfigPath);
         const jsonData = parseJsonc(fileContent);
-        configByFile = PartialConfigParamsSchema.parse(jsonData);
+        const parsed = ConfigFileSchema.parse(jsonData);
+        const { $schema: _schema, ...configParams2 } = parsed;
+        configByFile = configParams2;
       } catch (error) {
         logger.error(`Failed to load config file: ${formatError(error)}`);
         throw error;
@@ -642,6 +648,13 @@ var AiFile = class {
   setFileContent(newFileContent) {
     this.fileContent = newFileContent;
   }
+  /**
+   * Returns whether this file can be deleted by rulesync.
+   * Override in subclasses that should not be deleted (e.g., user-managed config files).
+   */
+  isDeletable() {
+    return true;
+  }
 };
 
 // src/features/commands/tool-command.ts
@@ -2301,6 +2314,13 @@ var ClaudecodeIgnore = class _ClaudecodeIgnore extends ToolIgnore {
       relativeFilePath: "settings.local.json"
     };
   }
+  /**
+   * ClaudecodeIgnore uses settings.local.json which is a user-managed config file.
+   * It should not be deleted by rulesync.
+   */
+  isDeletable() {
+    return false;
+  }
   toRulesyncIgnore() {
     const rulesyncPatterns = this.patterns.map((pattern) => {
       if (pattern.startsWith("Read(") && pattern.endsWith(")")) {
@@ -2791,7 +2811,7 @@ var IgnoreProcessor = class extends FeatureProcessor {
     try {
       const toolIgnores = await this.loadToolIgnores();
       if (forDeletion) {
-        return toolIgnores.filter((toolFile) => !(toolFile instanceof ClaudecodeIgnore));
+        return toolIgnores.filter((toolFile) => toolFile.isDeletable());
       }
       return toolIgnores;
     } catch (error) {
@@ -3293,6 +3313,14 @@ var ClaudecodeMcp = class _ClaudecodeMcp extends ToolMcp {
   getJson() {
     return this.json;
   }
+  /**
+   * In global mode, ~/.claude/.claude.json should not be deleted
+   * as it may contain other user settings.
+   * In local mode, .mcp.json can be safely deleted.
+   */
+  isDeletable() {
+    return !this.global;
+  }
   static getSettablePaths({ global } = {}) {
     if (global) {
       return {
@@ -3875,6 +3903,12 @@ var OpencodeMcp = class _OpencodeMcp extends ToolMcp {
   getJson() {
     return this.json;
   }
+  /**
+   * opencode.json may contain other settings, so it should not be deleted.
+   */
+  isDeletable() {
+    return false;
+  }
   static getSettablePaths({ global } = {}) {
     if (global) {
       return {
@@ -4159,11 +4193,7 @@ var McpProcessor = class extends FeatureProcessor {
       })();
       logger.info(`Successfully loaded ${toolMcps.length} ${this.toolTarget} MCP files`);
       if (forDeletion) {
-        let filteredMcps = toolMcps.filter((toolFile) => !(toolFile instanceof OpencodeMcp));
-        if (this.global) {
-          filteredMcps = filteredMcps.filter((toolFile) => !(toolFile instanceof ClaudecodeMcp));
-        }
-        return filteredMcps;
+        return toolMcps.filter((toolFile) => toolFile.isDeletable());
       }
       return toolMcps;
     } catch (error) {
@@ -4544,20 +4574,13 @@ var SimulatedSkill = class extends ToolSkill {
       name: rulesyncFrontmatter.name,
       description: rulesyncFrontmatter.description
     };
-    const otherFiles = rulesyncSkill.getOtherFiles();
-    if (otherFiles.length > 0) {
-      logger.warn(
-        `Skill "${rulesyncFrontmatter.name}" has ${otherFiles.length} additional file(s) that will be ignored for simulated skill generation.`
-      );
-    }
     return {
       baseDir: rulesyncSkill.getBaseDir(),
       relativeDirPath: this.getSettablePaths().relativeDirPath,
       dirName: rulesyncSkill.getDirName(),
       frontmatter: simulatedFrontmatter,
       body: rulesyncSkill.getBody(),
-      otherFiles: [],
-      // Simulated skills ignore otherFiles
+      otherFiles: rulesyncSkill.getOtherFiles(),
       validate
     };
   }
@@ -4579,14 +4602,19 @@ var SimulatedSkill = class extends ToolSkill {
     if (!result.success) {
       throw new Error(`Invalid frontmatter in ${skillFilePath}: ${formatError(result.error)}`);
     }
+    const otherFiles = await this.collectOtherFiles(
+      baseDir,
+      actualRelativeDirPath,
+      dirName,
+      SKILL_FILE_NAME
+    );
     return {
       baseDir,
       relativeDirPath: actualRelativeDirPath,
       dirName,
       frontmatter: result.data,
       body: content.trim(),
-      otherFiles: [],
-      // Simulated skills ignore otherFiles
+      otherFiles,
       validate: true
     };
   }
@@ -10001,13 +10029,247 @@ var ruleTools = {
   }
 };
 
-// src/mcp/subagents.ts
-import { basename as basename23, join as join86 } from "path";
+// src/mcp/skills.ts
+import { basename as basename23, dirname as dirname2, join as join86 } from "path";
 import { z as z35 } from "zod/mini";
+var maxSkillSizeBytes = 1024 * 1024;
+var maxSkillsCount = 1e3;
+function aiDirFileToMcpSkillFile(file) {
+  return {
+    name: file.relativeFilePathToDirPath,
+    body: file.fileBuffer.toString("utf-8")
+  };
+}
+function mcpSkillFileToAiDirFile(file) {
+  return {
+    relativeFilePathToDirPath: file.name,
+    fileBuffer: Buffer.from(file.body, "utf-8")
+  };
+}
+function extractDirName(relativeDirPathFromCwd) {
+  const dirName = basename23(relativeDirPathFromCwd);
+  if (!dirName) {
+    throw new Error(`Invalid path: ${relativeDirPathFromCwd}`);
+  }
+  return dirName;
+}
+async function listSkills() {
+  const skillsDir = join86(process.cwd(), RULESYNC_SKILLS_RELATIVE_DIR_PATH);
+  try {
+    const skillDirPaths = await findFilesByGlobs(join86(skillsDir, "*"), { type: "dir" });
+    const skills = await Promise.all(
+      skillDirPaths.map(async (dirPath) => {
+        const dirName = basename23(dirPath);
+        if (!dirName) return null;
+        try {
+          const skill = await RulesyncSkill.fromDir({
+            dirName
+          });
+          const frontmatter = skill.getFrontmatter();
+          return {
+            relativeDirPathFromCwd: join86(RULESYNC_SKILLS_RELATIVE_DIR_PATH, dirName),
+            frontmatter
+          };
+        } catch (error) {
+          logger.error(`Failed to read skill directory ${dirName}: ${formatError(error)}`);
+          return null;
+        }
+      })
+    );
+    return skills.filter((skill) => skill !== null);
+  } catch (error) {
+    logger.error(`Failed to read skills directory: ${formatError(error)}`);
+    return [];
+  }
+}
+async function getSkill({ relativeDirPathFromCwd }) {
+  checkPathTraversal({
+    relativePath: relativeDirPathFromCwd,
+    intendedRootDir: process.cwd()
+  });
+  const dirName = extractDirName(relativeDirPathFromCwd);
+  try {
+    const skill = await RulesyncSkill.fromDir({
+      dirName
+    });
+    return {
+      relativeDirPathFromCwd: join86(RULESYNC_SKILLS_RELATIVE_DIR_PATH, dirName),
+      frontmatter: skill.getFrontmatter(),
+      body: skill.getBody(),
+      otherFiles: skill.getOtherFiles().map(aiDirFileToMcpSkillFile)
+    };
+  } catch (error) {
+    throw new Error(
+      `Failed to read skill directory ${relativeDirPathFromCwd}: ${formatError(error)}`,
+      {
+        cause: error
+      }
+    );
+  }
+}
+async function putSkill({
+  relativeDirPathFromCwd,
+  frontmatter,
+  body,
+  otherFiles = []
+}) {
+  checkPathTraversal({
+    relativePath: relativeDirPathFromCwd,
+    intendedRootDir: process.cwd()
+  });
+  const dirName = extractDirName(relativeDirPathFromCwd);
+  const estimatedSize = JSON.stringify(frontmatter).length + body.length + otherFiles.reduce((acc, file) => acc + file.name.length + file.body.length, 0);
+  if (estimatedSize > maxSkillSizeBytes) {
+    throw new Error(
+      `Skill size ${estimatedSize} bytes exceeds maximum ${maxSkillSizeBytes} bytes (1MB)`
+    );
+  }
+  try {
+    const existingSkills = await listSkills();
+    const isUpdate = existingSkills.some(
+      (skill2) => skill2.relativeDirPathFromCwd === join86(RULESYNC_SKILLS_RELATIVE_DIR_PATH, dirName)
+    );
+    if (!isUpdate && existingSkills.length >= maxSkillsCount) {
+      throw new Error(`Maximum number of skills (${maxSkillsCount}) reached`);
+    }
+    const aiDirFiles = otherFiles.map(mcpSkillFileToAiDirFile);
+    const skill = new RulesyncSkill({
+      baseDir: process.cwd(),
+      relativeDirPath: RULESYNC_SKILLS_RELATIVE_DIR_PATH,
+      dirName,
+      frontmatter,
+      body,
+      otherFiles: aiDirFiles,
+      validate: true
+    });
+    const skillDirPath = join86(process.cwd(), RULESYNC_SKILLS_RELATIVE_DIR_PATH, dirName);
+    await ensureDir(skillDirPath);
+    const skillFilePath = join86(skillDirPath, SKILL_FILE_NAME);
+    const skillFileContent = stringifyFrontmatter(body, frontmatter);
+    await writeFileContent(skillFilePath, skillFileContent);
+    for (const file of otherFiles) {
+      checkPathTraversal({
+        relativePath: file.name,
+        intendedRootDir: skillDirPath
+      });
+      const filePath = join86(skillDirPath, file.name);
+      const fileDir = join86(skillDirPath, dirname2(file.name));
+      if (fileDir !== skillDirPath) {
+        await ensureDir(fileDir);
+      }
+      await writeFileContent(filePath, file.body);
+    }
+    return {
+      relativeDirPathFromCwd: join86(RULESYNC_SKILLS_RELATIVE_DIR_PATH, dirName),
+      frontmatter: skill.getFrontmatter(),
+      body: skill.getBody(),
+      otherFiles: skill.getOtherFiles().map(aiDirFileToMcpSkillFile)
+    };
+  } catch (error) {
+    throw new Error(
+      `Failed to write skill directory ${relativeDirPathFromCwd}: ${formatError(error)}`,
+      {
+        cause: error
+      }
+    );
+  }
+}
+async function deleteSkill({
+  relativeDirPathFromCwd
+}) {
+  checkPathTraversal({
+    relativePath: relativeDirPathFromCwd,
+    intendedRootDir: process.cwd()
+  });
+  const dirName = extractDirName(relativeDirPathFromCwd);
+  const skillDirPath = join86(process.cwd(), RULESYNC_SKILLS_RELATIVE_DIR_PATH, dirName);
+  try {
+    if (await directoryExists(skillDirPath)) {
+      await removeDirectory(skillDirPath);
+    }
+    return {
+      relativeDirPathFromCwd: join86(RULESYNC_SKILLS_RELATIVE_DIR_PATH, dirName)
+    };
+  } catch (error) {
+    throw new Error(
+      `Failed to delete skill directory ${relativeDirPathFromCwd}: ${formatError(error)}`,
+      {
+        cause: error
+      }
+    );
+  }
+}
+var McpSkillFileSchema = z35.object({
+  name: z35.string(),
+  body: z35.string()
+});
+var skillToolSchemas = {
+  listSkills: z35.object({}),
+  getSkill: z35.object({
+    relativeDirPathFromCwd: z35.string()
+  }),
+  putSkill: z35.object({
+    relativeDirPathFromCwd: z35.string(),
+    frontmatter: RulesyncSkillFrontmatterSchema,
+    body: z35.string(),
+    otherFiles: z35.optional(z35.array(McpSkillFileSchema))
+  }),
+  deleteSkill: z35.object({
+    relativeDirPathFromCwd: z35.string()
+  })
+};
+var skillTools = {
+  listSkills: {
+    name: "listSkills",
+    description: `List all skills from ${join86(RULESYNC_SKILLS_RELATIVE_DIR_PATH, "*", SKILL_FILE_NAME)} with their frontmatter.`,
+    parameters: skillToolSchemas.listSkills,
+    execute: async () => {
+      const skills = await listSkills();
+      const output = { skills };
+      return JSON.stringify(output, null, 2);
+    }
+  },
+  getSkill: {
+    name: "getSkill",
+    description: "Get detailed information about a specific skill including SKILL.md content and other files. relativeDirPathFromCwd parameter is required.",
+    parameters: skillToolSchemas.getSkill,
+    execute: async (args) => {
+      const result = await getSkill({ relativeDirPathFromCwd: args.relativeDirPathFromCwd });
+      return JSON.stringify(result, null, 2);
+    }
+  },
+  putSkill: {
+    name: "putSkill",
+    description: "Create or update a skill (upsert operation). relativeDirPathFromCwd, frontmatter, and body parameters are required. otherFiles is optional.",
+    parameters: skillToolSchemas.putSkill,
+    execute: async (args) => {
+      const result = await putSkill({
+        relativeDirPathFromCwd: args.relativeDirPathFromCwd,
+        frontmatter: args.frontmatter,
+        body: args.body,
+        otherFiles: args.otherFiles
+      });
+      return JSON.stringify(result, null, 2);
+    }
+  },
+  deleteSkill: {
+    name: "deleteSkill",
+    description: "Delete a skill directory and all its contents. relativeDirPathFromCwd parameter is required.",
+    parameters: skillToolSchemas.deleteSkill,
+    execute: async (args) => {
+      const result = await deleteSkill({ relativeDirPathFromCwd: args.relativeDirPathFromCwd });
+      return JSON.stringify(result, null, 2);
+    }
+  }
+};
+
+// src/mcp/subagents.ts
+import { basename as basename24, join as join87 } from "path";
+import { z as z36 } from "zod/mini";
 var maxSubagentSizeBytes = 1024 * 1024;
 var maxSubagentsCount = 1e3;
 async function listSubagents() {
-  const subagentsDir = join86(process.cwd(), RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH);
+  const subagentsDir = join87(process.cwd(), RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH);
   try {
     const files = await listDirectoryFiles(subagentsDir);
     const mdFiles = files.filter((file) => file.endsWith(".md"));
@@ -10020,7 +10282,7 @@ async function listSubagents() {
           });
           const frontmatter = subagent.getFrontmatter();
           return {
-            relativePathFromCwd: join86(RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, file),
+            relativePathFromCwd: join87(RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, file),
             frontmatter
           };
         } catch (error) {
@@ -10042,14 +10304,14 @@ async function getSubagent({ relativePathFromCwd }) {
     relativePath: relativePathFromCwd,
     intendedRootDir: process.cwd()
   });
-  const filename = basename23(relativePathFromCwd);
+  const filename = basename24(relativePathFromCwd);
   try {
     const subagent = await RulesyncSubagent.fromFile({
       relativeFilePath: filename,
       validate: true
     });
     return {
-      relativePathFromCwd: join86(RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, filename),
+      relativePathFromCwd: join87(RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, filename),
       frontmatter: subagent.getFrontmatter(),
       body: subagent.getBody()
     };
@@ -10068,7 +10330,7 @@ async function putSubagent({
     relativePath: relativePathFromCwd,
     intendedRootDir: process.cwd()
   });
-  const filename = basename23(relativePathFromCwd);
+  const filename = basename24(relativePathFromCwd);
   const estimatedSize = JSON.stringify(frontmatter).length + body.length;
   if (estimatedSize > maxSubagentSizeBytes) {
     throw new Error(
@@ -10078,7 +10340,7 @@ async function putSubagent({
   try {
     const existingSubagents = await listSubagents();
     const isUpdate = existingSubagents.some(
-      (subagent2) => subagent2.relativePathFromCwd === join86(RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, filename)
+      (subagent2) => subagent2.relativePathFromCwd === join87(RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, filename)
     );
     if (!isUpdate && existingSubagents.length >= maxSubagentsCount) {
       throw new Error(`Maximum number of subagents (${maxSubagentsCount}) reached`);
@@ -10091,11 +10353,11 @@ async function putSubagent({
       body,
       validate: true
     });
-    const subagentsDir = join86(process.cwd(), RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH);
+    const subagentsDir = join87(process.cwd(), RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH);
     await ensureDir(subagentsDir);
     await writeFileContent(subagent.getFilePath(), subagent.getFileContent());
     return {
-      relativePathFromCwd: join86(RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, filename),
+      relativePathFromCwd: join87(RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, filename),
       frontmatter: subagent.getFrontmatter(),
       body: subagent.getBody()
     };
@@ -10110,12 +10372,12 @@ async function deleteSubagent({ relativePathFromCwd }) {
     relativePath: relativePathFromCwd,
     intendedRootDir: process.cwd()
   });
-  const filename = basename23(relativePathFromCwd);
-  const fullPath = join86(process.cwd(), RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, filename);
+  const filename = basename24(relativePathFromCwd);
+  const fullPath = join87(process.cwd(), RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, filename);
   try {
     await removeFile(fullPath);
     return {
-      relativePathFromCwd: join86(RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, filename)
+      relativePathFromCwd: join87(RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, filename)
     };
   } catch (error) {
     throw new Error(
@@ -10127,23 +10389,23 @@ async function deleteSubagent({ relativePathFromCwd }) {
   }
 }
 var subagentToolSchemas = {
-  listSubagents: z35.object({}),
-  getSubagent: z35.object({
-    relativePathFromCwd: z35.string()
+  listSubagents: z36.object({}),
+  getSubagent: z36.object({
+    relativePathFromCwd: z36.string()
   }),
-  putSubagent: z35.object({
-    relativePathFromCwd: z35.string(),
+  putSubagent: z36.object({
+    relativePathFromCwd: z36.string(),
     frontmatter: RulesyncSubagentFrontmatterSchema,
-    body: z35.string()
+    body: z36.string()
   }),
-  deleteSubagent: z35.object({
-    relativePathFromCwd: z35.string()
+  deleteSubagent: z36.object({
+    relativePathFromCwd: z36.string()
   })
 };
 var subagentTools = {
   listSubagents: {
     name: "listSubagents",
-    description: `List all subagents from ${join86(RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, "*.md")} with their frontmatter.`,
+    description: `List all subagents from ${join87(RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, "*.md")} with their frontmatter.`,
     parameters: subagentToolSchemas.listSubagents,
     execute: async () => {
       const subagents = await listSubagents();
@@ -10190,7 +10452,7 @@ async function mcpCommand({ version }) {
     name: "Rulesync MCP Server",
     // eslint-disable-next-line no-type-assertion/no-type-assertion
     version,
-    instructions: "This server handles Rulesync files including rules, commands, MCP, ignore files, and subagents for any AI agents. It should be used when you need those files."
+    instructions: "This server handles Rulesync files including rules, commands, MCP, ignore files, subagents and skills for any AI agents. It should be used when you need those files."
   });
   server.addTool(ruleTools.listRules);
   server.addTool(ruleTools.getRule);
@@ -10204,6 +10466,10 @@ async function mcpCommand({ version }) {
   server.addTool(subagentTools.getSubagent);
   server.addTool(subagentTools.putSubagent);
   server.addTool(subagentTools.deleteSubagent);
+  server.addTool(skillTools.listSkills);
+  server.addTool(skillTools.getSkill);
+  server.addTool(skillTools.putSkill);
+  server.addTool(skillTools.deleteSkill);
   server.addTool(ignoreTools.getIgnoreFile);
   server.addTool(ignoreTools.putIgnoreFile);
   server.addTool(ignoreTools.deleteIgnoreFile);
@@ -10217,7 +10483,7 @@ async function mcpCommand({ version }) {
 }
 
 // src/cli/index.ts
-var getVersion = () => "3.28.1";
+var getVersion = () => "3.29.0";
 var main = async () => {
   const program = new Command();
   const version = getVersion();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulesync",
-  "version": "3.28.1",
+  "version": "3.29.0",
   "description": "Unified AI rules management CLI tool that generates configuration files for various AI development tools",
   "keywords": [
     "ai",
@@ -49,15 +49,15 @@
     "zod": "4.1.13"
   },
   "devDependencies": {
-    "@anthropic-ai/claude-agent-sdk": "0.1.53",
-    "@biomejs/biome": "2.3.7",
+    "@anthropic-ai/claude-agent-sdk": "0.1.55",
+    "@biomejs/biome": "2.3.8",
     "@eslint/js": "9.39.1",
     "@secretlint/secretlint-rule-preset-recommend": "11.2.5",
     "@tsconfig/node24": "24.0.3",
     "@types/js-yaml": "4.0.9",
     "@types/node": "24.10.1",
-    "@typescript/native-preview": "7.0.0-dev.20251125.1",
-    "@vitest/coverage-v8": "4.0.13",
+    "@typescript/native-preview": "7.0.0-dev.20251130.1",
+    "@vitest/coverage-v8": "4.0.14",
     "cspell": "9.3.2",
     "eslint": "9.39.1",
     "eslint-plugin-import": "2.32.0",
@@ -70,12 +70,12 @@
     "oxlint": "1.30.0",
     "secretlint": "11.2.5",
     "simple-git-hooks": "2.13.1",
-    "sort-package-json": "3.4.0",
+    "sort-package-json": "3.5.0",
     "tsup": "8.5.1",
-    "tsx": "4.20.6",
+    "tsx": "4.21.0",
     "typescript": "5.9.3",
     "typescript-eslint": "8.48.0",
-    "vitest": "4.0.13"
+    "vitest": "4.0.14"
   },
   "engines": {
     "node": ">=22.0.0"
@@ -98,6 +98,7 @@
     "eslint:fix": "eslint . --fix --max-warnings 0 --cache",
     "fix": "pnpm run bcheck:fix && pnpm run oxlint:fix && pnpm run eslint:fix",
     "generate": "pnpm run dev generate",
+    "generate:schema": "tsx scripts/generate-json-schema.ts",
     "knip": "knip",
     "oxlint": "oxlint . --max-warnings 0",
     "oxlint:fix": "oxlint . --fix --max-warnings 0",