@ww_nero/mini-cli 1.0.76 → 1.0.78

package/README.md

@@ -22,3 +22,19 @@
 ## 会话历史
 - 每个工作目录的历史记录保存在 `~/.mini/cli/<workspace-hash>/YYYYMMDDHHMMSS.json` 中。
 - 可通过 `mini --resume` 自动载入最近一次会话，或在对话中使用 `/resume` 按序号恢复。
+
+## Skills 支持
+- `mini` 会自动扫描 `~/.mini/skills/*/SKILL.md` 作为可用 skills。
+- 当你在提问中明确提到某个 skill 名称，或任务明显匹配某个 skill 描述时，模型会优先读取并遵循对应 skill。
+- 运行时可通过内置 `skills` 工具读取指定 skill 下的文件（默认 `SKILL.md`）。
+- 推荐目录结构示例：
+
+```text
+~/.mini/skills/
+  algorithmic-art/
+    SKILL.md
+    assets/
+    scripts/
+  docx/
+    SKILL.md
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ww_nero/mini-cli",
-  "version": "1.0.76",
+  "version": "1.0.78",
   "description": "极简的 AI 命令行助手",
   "bin": {
     "mini": "bin/mini.js"

package/src/chat.js

@@ -38,6 +38,7 @@ const {
   refreshHistoryFilePath
 } = require('./utils/history');
 const { selectFromList } = require('./utils/menu');
+const { discoverSkills, buildSkillsSystemPrompt } = require('./utils/skills');
 
 const CURSOR_STYLE_CODES = {
   default: '\u001B[0 q',
@@ -81,6 +82,25 @@ const appendMiniInstructions = (baseContent, workspaceRoot) => {
   return `${baseContent}\n\n${sections.join('\n\n')}`;
 };
 
+const appendSkillsInstructions = (baseContent) => {
+  const snapshot = discoverSkills();
+  const skillsSection = buildSkillsSystemPrompt(snapshot);
+
+  if (!skillsSection) {
+    return {
+      content: baseContent,
+      snapshot,
+      enabled: false
+    };
+  }
+
+  return {
+    content: `${baseContent}\n\n${skillsSection}`,
+    snapshot,
+    enabled: true
+  };
+};
+
 const formatWriteOutput = (result) => {
   if (!result || typeof result !== 'object' || !result.success) {
     return null;
@@ -254,7 +274,9 @@ const startChatSession = async ({
   if (initialCommitCreated) {
     console.log(chalk.gray('已创建初始提交：init project。'));
   }
-  const systemPromptContent = appendMiniInstructions(toolSystemPrompt, workspaceRoot);
+  const basePromptContent = appendMiniInstructions(toolSystemPrompt, workspaceRoot);
+  const skillsPromptResult = appendSkillsInstructions(basePromptContent);
+  const systemPromptContent = skillsPromptResult.content;
 
   // Load settings to get toolOutputTokenLimit and compactTokenThreshold
   const { settings } = loadSettings();
@@ -557,6 +579,15 @@ const startChatSession = async ({
     console.log(chalk.gray('未启用任何 MCP 服务器'));
   }
 
+  if (skillsPromptResult.snapshot && skillsPromptResult.snapshot.error) {
+    console.log(chalk.yellow(`skills 初始化失败: ${skillsPromptResult.snapshot.error}`));
+  } else if (skillsPromptResult.enabled) {
+    const skillNames = (skillsPromptResult.snapshot.skills || []).map((item) => item.name);
+    console.log(chalk.gray(`可用 skills (${skillNames.length}): ${skillNames.join(', ')}`));
+  } else {
+    console.log(chalk.gray('未发现可用 skills（可在 ~/.mini/skills/<skill>/SKILL.md 添加）'));
+  }
+
   const startupOptions = (Array.isArray(cliOptions) && cliOptions.length > 0) ? cliOptions : CLI_OPTIONS;
   if (startupOptions.length > 0) {
     console.log(chalk.gray('启动参数：'));
@@ -976,6 +1007,11 @@ const startChatSession = async ({
               if (toolContent) {
                 console.log(chalk.gray(`  ${toolContent}`));
               }
+            } else if (functionName === 'skills') {
+              const preview = truncateForDisplay(toolContent, 200);
+              if (preview) {
+                console.log(chalk.gray(`  ${preview}`));
+              }
             } else {
               // For other tools, show preview in gray
               const preview = truncateForDisplay(toolContent, 100);

package/src/config.js

@@ -12,12 +12,6 @@ const FILE_NAMES = {
   mini: 'MINI.md'
 };
 
-const DEFAULT_ALLOWED_COMMANDS = [
-  'rm', 'rmdir', 'touch', 'mkdir', 'cd', 'cp', 'mv', 'node', 'npm', 'pkill', 'kill',
-  'curl', 'ls', 'pwd', 'grep', 'cat', 'echo', 'sed', 'head', 'tail', 'find', 'true',
-  'false', 'pip', 'python', 'ps', 'lsof', 'git', 'pandoc'
-];
-
 const DEFAULT_TOOL_RESPONSE_MAX_TOKENS = 65536;
 const DEFAULT_COMPACT_TOKEN_THRESHOLD = 65536;
 const DEFAULT_MCP_TOOL_TIMEOUT_MS = 10 * 60 * 1000;
@@ -91,7 +85,6 @@ const DEFAULT_SETTINGS = {
   commands: [],
   maxToolTokens: DEFAULT_TOOL_RESPONSE_MAX_TOKENS,
   compactTokenThreshold: DEFAULT_COMPACT_TOKEN_THRESHOLD,
-  allowedCommands: [...DEFAULT_ALLOWED_COMMANDS],
   mcpToolTimeout: DEFAULT_MCP_TOOL_TIMEOUT_MS,
   outputMaxLength: DEFAULT_OUTPUT_MAX_LENGTH,
   executionTimeout: DEFAULT_EXECUTION_TIMEOUT,
@@ -345,10 +338,6 @@ const loadSettings = ({ defaultTools = [] } = {}) => {
       parsed.maxToolTokens,
       DEFAULT_TOOL_RESPONSE_MAX_TOKENS
     ),
-    allowedCommands: (() => {
-      const list = ensureArrayOfStrings(parsed.allowedCommands);
-      return list.length ? Array.from(new Set(list)) : [...DEFAULT_ALLOWED_COMMANDS];
-    })(),
     compactTokenThreshold: normalizePositiveInteger(
       parsed.compactTokenThreshold,
       DEFAULT_COMPACT_TOKEN_THRESHOLD
@@ -392,7 +381,6 @@ module.exports = {
   loadSettings,
   ensureConfigFiles,
   getConfigPath,
-  DEFAULT_ALLOWED_COMMANDS,
   DEFAULT_TOOL_RESPONSE_MAX_TOKENS,
   DEFAULT_COMPACT_TOKEN_THRESHOLD,
   COMPACT_SUMMARY_PROMPT

package/src/tools/bash.js

@@ -1,76 +1,5 @@
 const { spawn } = require('child_process');
 const { resolveWorkspacePath } = require('../utils/helpers');
-const { DEFAULT_ALLOWED_COMMANDS } = require('../config');
-
-// Git 只读命令白名单
-const GIT_READONLY_COMMANDS = ['show', 'diff', 'log', 'status', 'branch', 'tag', 'ls-files', 'ls-tree', 'rev-parse', 'reflog', 'blame', 'shortlog', 'describe', 'config --get', 'config --list', 'remote', 'ls-remote', 'fetch --dry-run', 'grep'];
-
-// Git 禁止的命令（会修改状态的命令）
-const GIT_FORBIDDEN_COMMANDS = ['add', 'commit', 'push', 'pull', 'merge', 'rebase', 'reset', 'revert', 'cherry-pick', 'apply', 'stash', 'clean', 'rm', 'mv', 'checkout', 'switch', 'restore', 'tag -a', 'tag -d', 'branch -d', 'branch -D', 'config --add', 'config --unset', 'submodule', 'clone', 'init'];
-
-const splitShellCommands = (commandString = '') => {
-  const operators = ['&&', '||'];
-  const pattern = '(' + operators.map(op => op.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|') + ')';
-  return commandString
-    .split(new RegExp(pattern))
-    .map(part => part.trim())
-    .filter(part => part && !operators.includes(part));
-};
-
-const validateSingleCommand = (commandString = '', allowedCommands = []) => {
-  const parts = commandString.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) || [];
-  if (parts.length === 0) {
-    return { isValid: false, reason: '命令为空' };
-  }
-
-  const command = parts[0];
-  if (!allowedCommands.includes(command)) {
-    return { isValid: false, reason: `命令 ${command} 不在允许名单内` };
-  }
-
-  if ((command === 'rm' || command === 'rmdir') && parts.slice(1).some(arg => !arg.startsWith('-') && arg.includes('.git'))) {
-    return { isValid: false, reason: '禁止对 .git 目录执行删除操作' };
-  }
-
-  // Git 命令额外验证
-  if (command === 'git') {
-    if (parts.length < 2) {
-      return { isValid: false, reason: 'git 命令缺少子命令' };
-    }
-
-    const gitSubCommand = parts[1];
-    const gitArgs = parts.slice(2).join(' ');
-    const fullGitCommand = gitSubCommand + (gitArgs ? ' ' + gitArgs : '');
-
-    // 检查是否是禁止的命令
-    for (const forbidden of GIT_FORBIDDEN_COMMANDS) {
-      if (gitSubCommand === forbidden || fullGitCommand.startsWith(forbidden)) {
-        return {
-          isValid: false,
-          reason: `禁止执行会修改仓库状态的 git 命令: ${forbidden}。只允许执行只读命令如: ${GIT_READONLY_COMMANDS.join(', ')}`
-        };
-      }
-    }
-
-    // 检查是否是允许的只读命令
-    let isReadOnly = false;
-    for (const readonly of GIT_READONLY_COMMANDS) {
-      if (gitSubCommand === readonly || fullGitCommand.startsWith(readonly)) {
-        isReadOnly = true;
-        break;
-      }
-    }
-
-    if (!isReadOnly) {
-      return {
-        isValid: false,
-        reason: `git 子命令 ${gitSubCommand} 不在只读命令白名单内。允许的命令: ${GIT_READONLY_COMMANDS.join(', ')}`
-      };
-    }
-  }
-
-  return { isValid: true, reason: '' };
-};
 
 const executeCommand = async ({ command, workingDirectory = '.', isService = false } = {}, context = {}) => {
   if (!command || typeof command !== 'string' || !command.trim()) {
@@ -79,30 +8,9 @@ const executeCommand = async ({ command, workingDirectory = '.', isService = fal
 
   const normalizedCommand = command.replace(/\bpython3\b/g, 'python');
 
-  const allowedCommands = Array.isArray(context.allowedCommands) && context.allowedCommands.length > 0
-    ? context.allowedCommands
-    : DEFAULT_ALLOWED_COMMANDS;
-
   const outputMaxLength = context.outputMaxLength || 12000;
   const executionTimeout = context.executionTimeout || 300000;
   const serviceBootWindow = context.serviceBootWindow || 5000;
-  const commands = splitShellCommands(normalizedCommand);
-  if (commands.length === 0) {
-    return '未找到有效的命令';
-  }
-
-  for (let i = 0; i < commands.length; i += 1) {
-    const validation = validateSingleCommand(commands[i], allowedCommands);
-    if (!validation.isValid) {
-      return [
-        '命令未通过安全校验',
-        `第 ${i + 1} 个指令: ${commands[i]}`,
-        `原因: ${validation.reason}`,
-        '允许的命令: ' + allowedCommands.join(', '),
-        '附加限制: rm/rmdir 禁止修改`.git`目录'
-      ].join('\n');
-    }
-  }
 
   let cwd;
   try {
@@ -196,14 +104,9 @@ const executeCommand = async ({ command, workingDirectory = '.', isService = fal
   });
 };
 
-const createBashToolSchema = (context = {}) => {
-  const allowedCommands = Array.isArray(context.allowedCommands) && context.allowedCommands.length > 0
-    ? context.allowedCommands
-    : DEFAULT_ALLOWED_COMMANDS;
+const createBashToolSchema = () => {
   const descriptionParts = ['在指定目录运行 bash 命令，支持使用 && / || 连接多个命令。'];
-  descriptionParts.push(`支持的命令: ${allowedCommands.join(', ')}。`);
-  descriptionParts.push('git 命令仅支持只读操作（show/diff/log/status 等），严禁执行 add/commit/push/reset 等会修改仓库状态的命令。');
-  descriptionParts.push('isService=true 时在后台运行服务，等待 5 秒返回初始输出，进程继续运行并持续捕获输出；默认等待命令执行完成，超时为 300 秒。');
+  descriptionParts.push('isService=true 时在后台运行服务，等待 5 秒返回初始输出，之后服务进程继续运行；默认等待命令执行完成，超时为 300 秒。');
 
   return {
     type: 'function',

package/src/tools/index.js

@@ -3,21 +3,20 @@ const read = require('./read');
 const write = require('./write');
 const replace = require('./replace');
 const todos = require('./todos');
+const skills = require('./skills');
 const { createMcpManager } = require('./mcp');
 const { loadSettings } = require('../config');
 
-const TOOL_MODULES = [bash, read, write, replace, todos];
+const TOOL_MODULES = [bash, read, write, replace, todos, skills];
 
 const createToolRuntime = async (workspaceRoot, options = {}) => {
   const defaultToolNames = TOOL_MODULES.map((tool) => tool.name);
   const { settings } = loadSettings({ defaultTools: defaultToolNames });
   const enabledTools = new Set(settings.tools && settings.tools.length > 0 ? settings.tools : defaultToolNames);
   const enabledMcps = Array.isArray(settings.mcps) ? settings.mcps : [];
-  const allowedCommands = settings.allowedCommands;
 
   const context = {
     workspaceRoot,
-    allowedCommands,
     outputMaxLength: settings.outputMaxLength,
     executionTimeout: settings.executionTimeout,
     serviceBootWindow: settings.serviceBootWindow,

package/src/tools/skills.js

@@ -0,0 +1,49 @@
+const { readSkillFile, toDisplayPath, SKILL_ENTRY_FILE } = require('../utils/skills');
+
+const handler = async ({ skillName, filePath } = {}) => {
+  try {
+    const result = readSkillFile({
+      skillName,
+      filePath
+    });
+
+    return {
+      success: true,
+      skillsRoot: toDisplayPath(result.skillsRoot),
+      skillName: result.skillName,
+      filePath: result.filePath,
+      absolutePath: result.absoluteFilePath,
+      content: result.content
+    };
+  } catch (error) {
+    return `读取 skill 失败：${error.message}`;
+  }
+};
+
+const schema = {
+  type: 'function',
+  function: {
+    name: 'skills',
+    description: '读取 ~/.mini/skills 下指定 skill 的文件内容（默认入口文件为 SKILL.md）',
+    parameters: {
+      type: 'object',
+      properties: {
+        skillName: {
+          type: 'string',
+          description: 'skill 名称'
+        },
+        filePath: {
+          type: 'string',
+          description: `相对于 skill 目录的文件路径，默认 ${SKILL_ENTRY_FILE}`
+        }
+      },
+      required: ['skillName']
+    }
+  }
+};
+
+module.exports = {
+  name: 'skills',
+  schema,
+  handler
+};

package/src/utils/settings.js

@@ -5,11 +5,6 @@ const path = require('path');
 const MINI_DIR_NAME = '.mini';
 const SETTINGS_FILE_NAME = 'settings.json';
 const DEFAULT_TOOL_OUTPUT_TOKEN_LIMIT = 32768;
-const DEFAULT_ALLOWED_COMMANDS = [
-  'rm', 'rmdir', 'touch', 'mkdir', 'cd', 'cp', 'mv', 'node', 'npm', 'ls',
-  'grep', 'cat', 'echo', 'sed', 'head', 'tail', 'find', 'true', 'false',
-  'pkill', 'kill', 'curl', 'ps', 'lsof', 'git', 'pip', 'python', 'pandoc'
-];
 
 const ensureArrayOfStrings = (value, fallback = []) => {
   if (!Array.isArray(value)) {
@@ -29,8 +24,7 @@ const loadSettings = ({ defaultTools = [] } = {}) => {
   const defaultSettings = {
     mcps: [],
     tools: [...defaultTools],
-    toolOutputTokenLimit: DEFAULT_TOOL_OUTPUT_TOKEN_LIMIT,
-    allowedCommands: [...DEFAULT_ALLOWED_COMMANDS]
+    toolOutputTokenLimit: DEFAULT_TOOL_OUTPUT_TOKEN_LIMIT
   };
 
   let parsed = null;
@@ -50,11 +44,6 @@ const loadSettings = ({ defaultTools = [] } = {}) => {
         parsed.toolOutputTokenLimit = DEFAULT_TOOL_OUTPUT_TOKEN_LIMIT;
         needsUpdate = true;
       }
-
-      if (!Array.isArray(parsed.allowedCommands)) {
-        parsed.allowedCommands = [...DEFAULT_ALLOWED_COMMANDS];
-        needsUpdate = true;
-      }
     } catch (error) {
       parsed = defaultSettings;
     }
@@ -65,8 +54,7 @@ const loadSettings = ({ defaultTools = [] } = {}) => {
     tools: ensureArrayOfStrings(parsed.tools, defaultSettings.tools),
     toolOutputTokenLimit: typeof parsed.toolOutputTokenLimit === 'number' && parsed.toolOutputTokenLimit > 0
       ? parsed.toolOutputTokenLimit
-      : DEFAULT_TOOL_OUTPUT_TOKEN_LIMIT,
-    allowedCommands: ensureArrayOfStrings(parsed.allowedCommands, DEFAULT_ALLOWED_COMMANDS)
+      : DEFAULT_TOOL_OUTPUT_TOKEN_LIMIT
   };
 
   if (needsUpdate) {
@@ -85,6 +73,5 @@ const loadSettings = ({ defaultTools = [] } = {}) => {
 
 module.exports = {
   loadSettings,
-  DEFAULT_TOOL_OUTPUT_TOKEN_LIMIT,
-  DEFAULT_ALLOWED_COMMANDS
+  DEFAULT_TOOL_OUTPUT_TOKEN_LIMIT
 };

package/src/utils/skills.js

@@ -0,0 +1,250 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const MINI_DIR_NAME = '.mini';
+const SKILLS_DIR_NAME = 'skills';
+const SKILL_ENTRY_FILE = 'SKILL.md';
+const MAX_DESCRIPTION_LENGTH = 160;
+
+const getSkillsRoot = () => path.join(os.homedir(), MINI_DIR_NAME, SKILLS_DIR_NAME);
+
+const toDisplayPath = (targetPath = '') => {
+  const absolutePath = path.resolve(String(targetPath || ''));
+  const homePath = path.resolve(os.homedir());
+  const relativePath = path.relative(homePath, absolutePath);
+
+  if (relativePath === '') {
+    return '~';
+  }
+
+  if (!relativePath.startsWith('..') && !path.isAbsolute(relativePath)) {
+    return `~/${relativePath.split(path.sep).join('/')}`;
+  }
+
+  return absolutePath;
+};
+
+const isPathInside = (basePath, targetPath) => {
+  const relativePath = path.relative(path.resolve(basePath), path.resolve(targetPath));
+  return relativePath === '' || (!relativePath.startsWith('..') && !path.isAbsolute(relativePath));
+};
+
+const trimDescription = (text = '') => {
+  const normalized = String(text || '').replace(/\s+/g, ' ').trim();
+  if (!normalized) {
+    return '';
+  }
+  if (normalized.length <= MAX_DESCRIPTION_LENGTH) {
+    return normalized;
+  }
+  return `${normalized.slice(0, MAX_DESCRIPTION_LENGTH)}...`;
+};
+
+const extractDescription = (content = '') => {
+  const normalized = String(content || '').replace(/\r/g, '');
+  if (!normalized.trim()) {
+    return '';
+  }
+
+  const taggedPattern = /^\s*(?:description|desc|简介|说明)\s*[:：]\s*(.+)$/im;
+  const taggedMatch = normalized.match(taggedPattern);
+  if (taggedMatch && taggedMatch[1]) {
+    return trimDescription(taggedMatch[1]);
+  }
+
+  const lines = normalized.split('\n');
+  let inCodeBlock = false;
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+
+    if (line.startsWith('```')) {
+      inCodeBlock = !inCodeBlock;
+      continue;
+    }
+
+    if (!line || inCodeBlock) {
+      continue;
+    }
+
+    if (
+      line.startsWith('#')
+      || line.startsWith('-')
+      || line.startsWith('*')
+      || line.startsWith('>')
+      || /^\d+[.)]\s/.test(line)
+    ) {
+      continue;
+    }
+
+    return trimDescription(line);
+  }
+
+  return '';
+};
+
+const discoverSkills = () => {
+  const skillsRoot = getSkillsRoot();
+
+  if (!fs.existsSync(skillsRoot)) {
+    return {
+      skillsRoot,
+      skills: []
+    };
+  }
+
+  let entries = [];
+
+  try {
+    entries = fs.readdirSync(skillsRoot, { withFileTypes: true });
+  } catch (error) {
+    return {
+      skillsRoot,
+      skills: [],
+      error: `读取 skills 目录失败：${error.message}`
+    };
+  }
+
+  const skills = entries
+    .filter((entry) => entry && entry.isDirectory() && !entry.name.startsWith('.'))
+    .map((entry) => {
+      const skillDirPath = path.join(skillsRoot, entry.name);
+      const entryFilePath = path.join(skillDirPath, SKILL_ENTRY_FILE);
+
+      if (!fs.existsSync(entryFilePath)) {
+        return null;
+      }
+
+      let description = '';
+      try {
+        const content = fs.readFileSync(entryFilePath, 'utf8');
+        description = extractDescription(content);
+      } catch (_) {
+        description = '';
+      }
+
+      return {
+        name: entry.name,
+        description,
+        dirPath: skillDirPath,
+        entryFilePath
+      };
+    })
+    .filter(Boolean)
+    .sort((left, right) => left.name.localeCompare(right.name));
+
+  return {
+    skillsRoot,
+    skills
+  };
+};
+
+const resolveSkillDirectory = (skillsRoot, skillName) => {
+  if (typeof skillName !== 'string' || !skillName.trim()) {
+    throw new Error('skillName 参数不能为空');
+  }
+
+  const normalizedName = skillName.trim();
+  const skillDirPath = path.resolve(skillsRoot, normalizedName);
+
+  if (!isPathInside(skillsRoot, skillDirPath)) {
+    throw new Error('skillName 非法，不能超出 skills 目录');
+  }
+
+  if (path.resolve(path.dirname(skillDirPath)) !== path.resolve(skillsRoot)) {
+    throw new Error('skillName 必须是 skills 目录下的直接子目录名');
+  }
+
+  if (!fs.existsSync(skillDirPath) || !fs.statSync(skillDirPath).isDirectory()) {
+    throw new Error(`skill 不存在: ${normalizedName}`);
+  }
+
+  return {
+    skillName: normalizedName,
+    skillDirPath
+  };
+};
+
+const resolveSkillFilePath = (skillDirPath, filePath = SKILL_ENTRY_FILE) => {
+  const normalizedFilePath = typeof filePath === 'string' && filePath.trim()
+    ? filePath.trim()
+    : SKILL_ENTRY_FILE;
+
+  if (path.isAbsolute(normalizedFilePath)) {
+    throw new Error('filePath 必须是相对于 skill 目录的路径');
+  }
+
+  const absoluteFilePath = path.resolve(skillDirPath, normalizedFilePath);
+
+  if (!isPathInside(skillDirPath, absoluteFilePath)) {
+    throw new Error('filePath 非法，不能超出 skill 目录');
+  }
+
+  if (!fs.existsSync(absoluteFilePath) || !fs.statSync(absoluteFilePath).isFile()) {
+    throw new Error(`文件不存在: ${normalizedFilePath}`);
+  }
+
+  const relativeFilePath = path.relative(skillDirPath, absoluteFilePath).split(path.sep).join('/');
+
+  return {
+    absoluteFilePath,
+    relativeFilePath
+  };
+};
+
+const readSkillFile = ({ skillName, filePath } = {}) => {
+  const skillsRoot = getSkillsRoot();
+  if (!fs.existsSync(skillsRoot)) {
+    throw new Error(`skills 目录不存在: ${toDisplayPath(skillsRoot)}`);
+  }
+
+  const { skillName: normalizedSkillName, skillDirPath } = resolveSkillDirectory(skillsRoot, skillName);
+  const { absoluteFilePath, relativeFilePath } = resolveSkillFilePath(skillDirPath, filePath);
+  const content = fs.readFileSync(absoluteFilePath, 'utf8');
+
+  return {
+    skillsRoot,
+    skillName: normalizedSkillName,
+    skillDirPath,
+    filePath: relativeFilePath,
+    absoluteFilePath,
+    content
+  };
+};
+
+const buildSkillsSystemPrompt = (snapshot = {}) => {
+  const skills = Array.isArray(snapshot.skills) ? snapshot.skills : [];
+  if (skills.length === 0) {
+    return '';
+  }
+
+  const lines = [
+    '<skills>',
+    `skills 目录: ${toDisplayPath(snapshot.skillsRoot || getSkillsRoot())}`,
+    '当用户明确提到某个 skill，或任务明显匹配某个 skill 描述时，优先使用该 skill。',
+    'skill 使用流程：',
+    '1. 先调用 skills 工具读取对应 skill 的 SKILL.md。',
+    '2. 若 SKILL.md 引用其他文件，再调用 skills 工具按需读取。',
+    '3. 仅加载当前任务需要的内容，避免无关读取。',
+    '可用 skills：'
+  ];
+
+  skills.forEach((skill) => {
+    const description = skill.description || '（暂无描述）';
+    lines.push(`- ${skill.name}: ${description}`);
+  });
+
+  lines.push('</skills>');
+
+  return lines.join('\n');
+};
+
+module.exports = {
+  SKILL_ENTRY_FILE,
+  getSkillsRoot,
+  discoverSkills,
+  readSkillFile,
+  toDisplayPath,
+  buildSkillsSystemPrompt
+};