@jiangyuan1209/yuan-claw 0.1.2 → 0.1.3

package/README.md

@@ -1,3 +1,4 @@
+```md
 # yuan-claw
 
 一个基于 **Node.js + TypeScript** 的本地 CLI Agent。  
@@ -14,7 +15,8 @@
 - 🖥️ 支持交互式 REPL
 - ✅ 支持工具执行前确认（approval）
 - ⌨️ 支持 `↑ / ↓ / Enter` 选择确认项
-- 🔁 支持会话级“总是允许”模式
+- 🔁 支持会话级”总是允许”模式
+- 📦 支持本地 Skill 插件扩展能力
 - 🔌 支持代理配置
 - 🛠️ 基于 TypeScript，便于二次开发
 
@@ -29,80 +31,236 @@
 
 ## Installation
 
+### 方式一：通过 npm 全局安装（推荐）
+
+```bash
+npm install -g @jiangyuan1209/yuan-claw
+```
+
+安装完成后可直接使用：
+
+```bash
+yuan-claw
+```
+
+卸载命令：
+
+```bash
+npm uninstall -g @jiangyuan1209/yuan-claw
+```
+
+如需安装指定版本：
+
+```bash
+npm install -g @jiangyuan1209/yuan-claw@0.1.2
+```
+
+升级到最新版：
+
+```bash
+npm install -g @jiangyuan1209/yuan-claw@latest
+```
+
+---
+
+### 方式二：从源码安装
+
 ```bash
 git clone https://github.com/your-name/yuan-claw.git
 cd yuan-claw
 npm install
+npm run build
+```
+
+源码模式下运行：
+
+```bash
+npm run dev
+```
+
+或：
+
+```bash
+npm run start
 ```
 
 ---
 
 ## Quick Start
 
-### 1. 配置环境变量
+### 1. 首次运行初始化配置
 
-在项目根目录创建 `.env` 文件：
+安装完成后，先执行一次：
 
-```env
-MODEL_API_KEY=
-MODEL_BASE_URL=
-MODEL_NAME=
+```bash
+yuan-claw
+```
 
-BRAVE_SEARCH_API_KEY=
+程序会在你的用户目录下自动初始化配置文件：
 
-HTTP_PROXY=
-HTTPS_PROXY=
+```bash
+~/.yuan-claw/settings.json
+```
+
+在 macOS / Linux 上通常类似：
+
+```bash
+/Users/你的用户名/.yuan-claw/settings.json
+```
+
+如果你使用的是 Windows，则通常位于用户目录下对应的 `.yuan-claw` 文件夹中。
+
+> 注意：第一次运行通常只是创建配置文件。  
+> 你需要手动填写配置后，再次执行 `yuan-claw` 才会真正生效。
+
+---
+
+### 2. 编辑 `~/.yuan-claw/settings.json`
+
+示例：
+
+```json
+{
+  "MODEL_API_KEY": "your_api_key",
+  "MODEL_BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+  "MODEL_NAME": "qwen3-max-2026-01-23",
+  "BRAVE_SEARCH_API_KEY": "your_brave_search_api_key",
+  "HTTP_PROXY": "http://127.0.0.1:33210",
+  "HTTPS_PROXY": "http://127.0.0.1:33210"
+}
 ```
 
 最小可用配置通常只需要：
 
-```env
-MODEL_API_KEY=your_api_key
-MODEL_BASE_URL=https://api.openai.com/v1
-MODEL_NAME=gpt-4o-mini
+```json
+{
+  "MODEL_API_KEY": "your_api_key",
+  "MODEL_BASE_URL": "https://api.openai.com/v1",
+  "MODEL_NAME": "gpt-4o-mini"
+}
+```
+
+如果你希望启用网页搜索，还可以配置：
+
+```json
+{
+  "BRAVE_SEARCH_API_KEY": "your_brave_search_api_key"
+}
+```
+
+如需使用代理，可以配置：
+
+```json
+{
+  "HTTP_PROXY": "http://127.0.0.1:33210",
+  "HTTPS_PROXY": "http://127.0.0.1:33210"
+}
+```
+
+保存后，重新执行：
+
+```bash
+yuan-claw
 ```
 
 ---
 
-### 2. 开发模式运行
+### 3. 开始使用
+
+#### 交互式 REPL
+
+```bash
+yuan-claw
+```
 
 #### 单次命令
 
 ```bash
-npm run dev -- "帮我搜索 OpenAI 最新消息"
+yuan-claw "帮我搜索 OpenAI 最新消息"
 ```
 
-#### 交互式 REPL
+---
+
+## Configuration
+
+项目优先从用户目录中的配置文件读取配置：
 
 ```bash
-npm run dev
+~/.yuan-claw/settings.json
 ```
 
-启动后你会看到：
+### 支持的配置项
 
-```txt
-Welcome to yuan-claw!
-Type /help for commands, /exit to quit.
-Approval mode is shown in the prompt: [ask] or [always].
+- `MODEL_API_KEY`
+- `MODEL_BASE_URL`
+- `MODEL_NAME`
+- `OPENAI_API_KEY`
+- `OPENAI_BASE_URL`
+- `OPENAI_MODEL`
+- `BRAVE_SEARCH_API_KEY`
+- `HTTP_PROXY`
+- `HTTPS_PROXY`
+- `http_proxy`
+- `https_proxy`
 
-yuan-claw[ask]>
+### 推荐配置示例
+
+#### OpenAI-compatible 通用配置
+
+```json
+{
+  "MODEL_API_KEY": "your_api_key",
+  "MODEL_BASE_URL": "https://api.openai.com/v1",
+  "MODEL_NAME": "gpt-4o-mini"
+}
+```
+
+#### DashScope 示例
+
+```json
+{
+  "MODEL_API_KEY": "your_dashscope_api_key",
+  "MODEL_BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+  "MODEL_NAME": "qwen3-max-2026-01-23",
+  "BRAVE_SEARCH_API_KEY": "your_brave_search_api_key",
+  "HTTP_PROXY": "http://127.0.0.1:33210",
+  "HTTPS_PROXY": "http://127.0.0.1:33210"
+}
 ```
 
 ---
 
-### 3. 编译后运行
+## Environment Variables（兼容方式）
 
-```bash
-npm run build
-npm run start
+除了 `~/.yuan-claw/settings.json` 外，开发者也可以在项目根目录通过 `.env` 配置：
+
+```env
+MODEL_API_KEY=
+MODEL_BASE_URL=
+MODEL_NAME=
+
+BRAVE_SEARCH_API_KEY=
+
+HTTP_PROXY=
+HTTPS_PROXY=
 ```
 
-单次命令模式：
+也支持 OpenAI 风格变量名：
 
-```bash
-npm run start -- "帮我总结这个项目的功能"
+```env
+OPENAI_API_KEY=
+OPENAI_BASE_URL=
+OPENAI_MODEL=
 ```
 
+> 普通 CLI 用户更推荐使用：
+>
+> ```bash
+> ~/.yuan-claw/settings.json
+> ```
+>
+> `.env` 更适合源码开发或本地调试。
+
 ---
 
 ## REPL Usage
@@ -163,86 +321,37 @@ yuan-claw[always]>
 
 ---
 
-## Scripts
-
-```json
-{
-  "scripts": {
-    "dev": "tsx src/cli/main.ts",
-    "build": "tsc -p tsconfig.json",
-    "start": "node dist/cli/main.js",
-    "check": "tsc --noEmit"
-  }
-}
-```
-
-### 脚本说明
-
-- `npm run dev`：开发模式运行源码
-- `npm run build`：编译到 `dist/`
-- `npm run start`：运行编译后的 CLI
-- `npm run check`：执行 TypeScript 类型检查
-
-说明：
-
-- `npm run dev` / `npm run start`
-    - 不传参数：进入 REPL
-    - 传入参数：执行单次命令
-
----
-
 ## CLI Usage
 
-项目在 `package.json` 中定义了可执行命令：
-
-```json
-"bin": {
-  "yuan-claw": "./dist/cli/main.js"
-}
-```
-
-构建并安装后，可以直接使用：
+全局安装后可直接运行：
 
 ```bash
 yuan-claw
 ```
 
-或：
+单次命令模式：
 
 ```bash
 yuan-claw "帮我搜索 AI 新闻"
 ```
 
----
-
-## Environment Variables
-
-项目使用 **OpenAI-compatible API**，按以下优先级读取配置：
+如果你是源码模式开发，则可以使用：
 
-### API Key
-
-1. `MODEL_API_KEY`
-2. `OPENAI_API_KEY`
-
-### Base URL
-
-1. `MODEL_BASE_URL`
-2. `OPENAI_BASE_URL`
-
-### Model Name
+```bash
+npm run dev
+```
 
-1. `MODEL_NAME`
-2. `OPENAI_MODEL`
-3. 默认值：`gpt-4o-mini`
+或：
 
-### OpenAI 风格兼容变量
+```bash
+npm run dev -- "帮我总结这个项目的功能"
+```
 
-如果你更习惯 OpenAI 风格变量名，也可以使用：
+编译后运行：
 
-```env
-OPENAI_API_KEY=
-OPENAI_BASE_URL=
-OPENAI_MODEL=
+```bash
+npm run build
+npm run start
 ```
 
 ---
@@ -251,8 +360,10 @@ OPENAI_MODEL=
 
 如果你希望启用网页搜索工具，请配置：
 
-```env
-BRAVE_SEARCH_API_KEY=your_brave_search_api_key
+```json
+{
+  "BRAVE_SEARCH_API_KEY": "your_brave_search_api_key"
+}
 ```
 
 未配置时，`web_search` 工具会被禁用。
@@ -263,12 +374,14 @@ BRAVE_SEARCH_API_KEY=your_brave_search_api_key
 
 如需通过代理访问模型服务或外部网站，可以配置：
 
-```env
-HTTP_PROXY=http://127.0.0.1:33210
-HTTPS_PROXY=http://127.0.0.1:33210
+```json
+{
+  "HTTP_PROXY": "http://127.0.0.1:33210",
+  "HTTPS_PROXY": "http://127.0.0.1:33210"
+}
 ```
 
-程序会自动读取以下变量：
+程序会自动读取以下配置项：
 
 - `HTTP_PROXY`
 - `HTTPS_PROXY`
@@ -277,41 +390,124 @@ HTTPS_PROXY=http://127.0.0.1:33210
 
 ---
 
-## Recommended `.env.example`
+## Skills / 本地插件扩展
 
-建议在仓库中提供如下 `.env.example`：
+yuan-claw 支持通过本地 Skill（技能）文件扩展 Agent 的能力。Skill 是存放在固定目录下的 Markdown 文件，Agent 会在运行时根据用户输入自动匹配并加载相关 Skill 的提示词，从而获得领域知识或操作指引。
 
-```env
-# =========================
-# 模型服务配置（推荐）
-# =========================
+### Skill 目录结构
 
-MODEL_API_KEY=
-MODEL_BASE_URL=
-MODEL_NAME=
+所有 Skill 文件存放在：
 
-# =========================
-# OpenAI 风格兼容变量（可选）
-# =========================
+```bash
+~/.yuan-claw/skills/
+```
 
-OPENAI_API_KEY=
-OPENAI_BASE_URL=
-OPENAI_MODEL=
+每个 Skill 是一个子目录，其中必须包含一个 `SKILL.md` 文件：
 
-# =========================
-# 网页搜索配置
-# =========================
+```
+~/.yuan-claw/skills/
+├── pdf/
+│   └── SKILL.md
+├── frontend-design/
+│   └── SKILL.md
+└── my-skill/
+    └── SKILL.md
+```
 
-BRAVE_SEARCH_API_KEY=
+### SKILL.md 文件格式
 
-# =========================
-# 代理配置（可选）
-# =========================
+`SKILL.md` 使用 YAML frontmatter + Markdown body 的格式：
 
-HTTP_PROXY=
-HTTPS_PROXY=
+```markdown
+---
+name: pdf
+description: PDF 文件处理技能，支持提取文本、表格、OCR 等
+tags: [pdf, document, ocr]
+license: MIT
+version: 1.0.0
+---
+
+## 使用指南
+
+当用户需要处理 PDF 文件时：
+1. 使用 pdfplumber 提取文本...
+2. 对于扫描件，使用 OCR...
 ```
 
+Frontmatter 字段说明：
+
+- `name`（可选）：Skill 名称，用于匹配和展示。未填写时使用目录名
+- `description`（可选）：简短描述，用于匹配和展示
+- `tags`（可选）：标签数组，用于关键词匹配
+- `license`（可选）：许可证
+- `version`（可选）：版本号
+
+Markdown body 是 Skill 的实际提示词内容，会被注入到 system prompt 中指导 Agent 行为。
+
+### 匹配机制
+
+Agent 会根据用户输入自动匹配最相关的 Skill（最多匹配 3 个），匹配依据包括：
+
+- 用户输入中是否包含 Skill 名称
+- 用户输入中是否包含 Skill 的标签
+- 用户输入分词后与 Skill 描述的关键词重合度
+
+匹配到的 Skill 内容会被组装到 system prompt 中，指导 Agent 使用相应的知识和流程。
+
+### 添加自定义 Skill
+
+1. 在 `~/.yuan-claw/skills/` 下创建新目录：
+
+```bash
+mkdir -p ~/.yuan-claw/skills/my-skill
+```
+
+2. 创建 `SKILL.md` 文件：
+
+```bash
+cat > ~/.yuan-claw/skills/my-skill/SKILL.md << 'EOF'
+---
+name: my-skill
+description: 我的自定义技能
+tags: [custom]
+---
+
+当用户问到 XXX 时，请按以下步骤操作：
+1. ...
+2. ...
+EOF
+```
+
+3. 下次运行 `yuan-claw` 时，该 Skill 会被自动发现和加载。
+
+---
+
+## Scripts
+
+```json
+{
+  "scripts": {
+    "dev": "tsx src/cli/main.ts",
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/cli/main.js",
+    "check": "tsc --noEmit"
+  }
+}
+```
+
+### 脚本说明
+
+- `npm run dev`：开发模式运行源码
+- `npm run build`：编译到 `dist/`
+- `npm run start`：运行编译后的 CLI
+- `npm run check`：执行 TypeScript 类型检查
+
+说明：
+
+- `npm run dev` / `npm run start`
+    - 不传参数：进入 REPL
+    - 传入参数：执行单次命令
+
 ---
 
 ## Examples
@@ -319,17 +515,23 @@ HTTPS_PROXY=
 ### 普通问答
 
 ```bash
-npm run dev -- "帮我总结这个项目的功能"
+yuan-claw "帮我总结这个项目的功能"
 ```
 
 ### 搜索最新消息
 
 ```bash
-npm run dev -- "帮我搜索 OpenAI 最新消息"
+yuan-claw "帮我搜索 OpenAI 最新消息"
 ```
 
 ### 进入 REPL
 
+```bash
+yuan-claw
+```
+
+### 源码开发模式
+
 ```bash
 npm run dev
 ```
@@ -345,18 +547,42 @@ npm run start -- "帮我搜索 AI 新闻"
 
 ## Troubleshooting
 
-### `Missing MODEL_API_KEY / OPENAI_API_KEY in environment variables.`
+### 第一次运行后为什么没有立即生效？
 
-说明模型 API Key 未配置。请至少设置其一：
+因为第一次执行：
 
-```env
-MODEL_API_KEY=your_api_key
+```bash
+yuan-claw
 ```
 
-或：
+通常只是为了初始化配置文件：
 
-```env
-OPENAI_API_KEY=your_api_key
+```bash
+~/.yuan-claw/settings.json
+```
+
+你需要手动填写配置项并保存，然后再次执行：
+
+```bash
+yuan-claw
+```
+
+---
+
+### `Missing MODEL_API_KEY / OPENAI_API_KEY in environment variables.`
+
+说明模型 API Key 尚未正确配置。请至少在以下任一位置填写：
+
+- `~/.yuan-claw/settings.json`
+- 系统环境变量
+- 项目根目录 `.env`
+
+例如：
+
+```json
+{
+  "MODEL_API_KEY": "your_api_key"
+}
 ```
 
 ---
@@ -365,19 +591,23 @@ OPENAI_API_KEY=your_api_key
 
 说明未配置 Brave Search API Key。请添加：
 
-```env
-BRAVE_SEARCH_API_KEY=your_key
+```json
+{
+  "BRAVE_SEARCH_API_KEY": "your_brave_search_api_key"
+}
 ```
 
 ---
 
 ### 无法访问外部服务 / 请求超时
 
-请检查是否需要代理：
+请检查是否需要代理，例如：
 
-```env
-HTTP_PROXY=http://127.0.0.1:33210
-HTTPS_PROXY=http://127.0.0.1:33210
+```json
+{
+  "HTTP_PROXY": "http://127.0.0.1:33210",
+  "HTTPS_PROXY": "http://127.0.0.1:33210"
+}
 ```
 
 ---
@@ -405,13 +635,33 @@ dist/cli/main.js
 
 ---
 
+### 全局命令 `yuan-claw` 不存在
+
+如果你是通过 npm 全局安装，请确认已成功安装：
+
+```bash
+npm install -g @jiangyuan1209/yuan-claw
+```
+
+如仍有问题，可尝试重新安装：
+
+```bash
+npm uninstall -g @jiangyuan1209/yuan-claw
+npm install -g @jiangyuan1209/yuan-claw@latest
+```
+
+---
+
 ## Development
 
 ```bash
+npm install
 npm run check
 npm run dev
 ```
 
+如果你使用源码开发方式，也可以在项目根目录创建 `.env` 文件辅助调试。
+
 ---
 
 ## Roadmap
@@ -428,14 +678,4 @@ npm run dev
 
 ## License
 
-MIT
-```
-
-
-## `.gitignore`
-
-```gitignore
-node_modules
-dist
-.env
-```
+MIT

package/dist/agent/build-system-prompt.js

@@ -9,7 +9,10 @@ function formatToolsForPrompt(tools) {
     })
         .join("\n");
 }
-export function buildSystemPrompt(tools) {
+export function buildSystemPrompt(tools, skillsPrompt) {
+    const skillsSection = skillsPrompt
+        ? ["", "LOCAL SKILLS:", skillsPrompt].join("\n")
+        : "";
     return [
         "You are a local CLI coding agent.",
         "You do not have direct filesystem, shell, git, or network access unless you use the provided tools.",
@@ -37,6 +40,7 @@ export function buildSystemPrompt(tools) {
         "",
         "AVAILABLE TOOLS:",
         formatToolsForPrompt(tools),
+        skillsSection,
         "",
         "Examples:",
         '{"type":"tool_call","toolName":"read_file","args":{"path":"package.json"}}',

package/dist/agent/run-local-agent-loop.js

@@ -1,5 +1,6 @@
 import { buildSystemPrompt } from "./build-system-prompt.js";
 import { parseAgentResponse } from "./parse-agent-response.js";
+import { SkillsRuntime } from "../skills/runtime.js";
 function stringifyForModel(value) {
     try {
         return JSON.stringify(value);
@@ -30,11 +31,15 @@ export async function runLocalAgentLoop(params) {
         type: "run_start",
         input: userInput,
     });
+    // Load and match skills based on user input
+    const skillsRuntime = new SkillsRuntime();
+    await skillsRuntime.reload();
+    const skillsPrompt = skillsRuntime.buildPromptForInput(userInput);
     const historyMessages = previousMessages.filter((message) => message.role !== "system");
     const messages = [
         {
             role: "system",
-            content: buildSystemPrompt(Array.from(tools.values())),
+            content: buildSystemPrompt(Array.from(tools.values()), skillsPrompt),
         },
         ...historyMessages,
         {

package/dist/cli/main.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-import "dotenv/config";
 import { select, cancel, isCancel } from "@clack/prompts";
 import { initGlobalProxy } from "../lib/initGlobalProxy.js";
 import { parseCliArgs } from "./parse-args.js";

package/dist/config/load-config.js

@@ -27,20 +27,5 @@ async function loadSettingsFile() {
     }
 }
 export async function loadAppConfig() {
-    const fileConfig = await loadSettingsFile();
-    return {
-        ...fileConfig,
-        MODEL_API_KEY: process.env.MODEL_API_KEY ?? fileConfig.MODEL_API_KEY,
-        MODEL_BASE_URL: process.env.MODEL_BASE_URL ?? fileConfig.MODEL_BASE_URL,
-        MODEL_NAME: process.env.MODEL_NAME ?? fileConfig.MODEL_NAME,
-        OPENAI_API_KEY: process.env.OPENAI_API_KEY ?? fileConfig.OPENAI_API_KEY,
-        OPENAI_BASE_URL: process.env.OPENAI_BASE_URL ?? fileConfig.OPENAI_BASE_URL,
-        OPENAI_MODEL: process.env.OPENAI_MODEL ?? fileConfig.OPENAI_MODEL,
-        BRAVE_SEARCH_API_KEY: process.env.BRAVE_SEARCH_API_KEY ?? fileConfig.BRAVE_SEARCH_API_KEY,
-        BRAVE_API_KEY: process.env.BRAVE_API_KEY ?? fileConfig.BRAVE_API_KEY,
-        HTTP_PROXY: process.env.HTTP_PROXY ?? fileConfig.HTTP_PROXY,
-        HTTPS_PROXY: process.env.HTTPS_PROXY ?? fileConfig.HTTPS_PROXY,
-        http_proxy: process.env.http_proxy ?? fileConfig.http_proxy,
-        https_proxy: process.env.https_proxy ?? fileConfig.https_proxy,
-    };
+    return await loadSettingsFile();
 }

package/dist/model/providers/openai-compatible.js

@@ -1,20 +1,9 @@
 import OpenAI from "openai";
 export function createOpenAICompatibleClient(options = {}) {
     const config = options.config ?? {};
-    const apiKey = config.MODEL_API_KEY ??
-        config.OPENAI_API_KEY ??
-        process.env.MODEL_API_KEY ??
-        process.env.OPENAI_API_KEY;
-    const baseURL = config.MODEL_BASE_URL ??
-        config.OPENAI_BASE_URL ??
-        process.env.MODEL_BASE_URL ??
-        process.env.OPENAI_BASE_URL;
-    const model = options.model ??
-        config.MODEL_NAME ??
-        config.OPENAI_MODEL ??
-        process.env.MODEL_NAME ??
-        process.env.OPENAI_MODEL ??
-        "gpt-4o-mini";
+    const apiKey = config.MODEL_API_KEY;
+    const baseURL = config.MODEL_BASE_URL;
+    const model = config.MODEL_NAME ?? "gpt-4o-mini";
     if (!apiKey) {
         throw new Error("Missing MODEL_API_KEY / OPENAI_API_KEY in environment variables or ~/.my-agent/settings.json.");
     }

package/dist/security/path-guards.js

@@ -3,6 +3,11 @@ export function resolveWorkspaceRoot(workspaceRoot) {
     return path.resolve(workspaceRoot ?? process.cwd());
 }
 export function resolveSafePath(workspaceRoot, targetPath) {
+    // If the target is an absolute path, allow reading it directly (anywhere on disk)
+    if (path.isAbsolute(targetPath)) {
+        return path.resolve(targetPath);
+    }
+    // Relative paths are resolved against the workspace root
     const root = path.resolve(workspaceRoot);
     const fullPath = path.resolve(root, targetPath);
     const relative = path.relative(root, fullPath);

package/dist/security/shell-policy.js

@@ -1,3 +1,4 @@
+import path from "node:path";
 const DEFAULT_DENY_PATTERNS = [
     /\brm\s+-rf\s+\//i,
     /\bsudo\b/i,
@@ -22,6 +23,14 @@ const DEFAULT_ALLOW_PREFIXES = [
     "npm",
     "node",
     "git",
+    "python3",
+    "python",
+    "pip3",
+    "pip",
+    "pdftotext",
+    "qpdf",
+    "pandoc",
+    "which",
 ];
 export function validateShellCommand(command) {
     const trimmed = command.trim();
@@ -34,7 +43,11 @@ export function validateShellCommand(command) {
         }
     }
     const firstToken = trimmed.split(/\s+/)[0];
-    if (!DEFAULT_ALLOW_PREFIXES.includes(firstToken)) {
+    // Also allow absolute paths ending with known commands (e.g. /usr/bin/python3)
+    const commandName = firstToken.includes(path.sep)
+        ? path.basename(firstToken)
+        : firstToken;
+    if (!DEFAULT_ALLOW_PREFIXES.includes(commandName)) {
         throw new Error(`Shell command not allowed by policy. Command prefix: ${firstToken}`);
     }
 }

package/dist/skills/discover.js

@@ -0,0 +1,24 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ensureSkillsDir } from "./paths.js";
+export async function discoverSkillDirs() {
+    const skillsDir = await ensureSkillsDir();
+    const entries = await fs.readdir(skillsDir, { withFileTypes: true });
+    const result = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const dir = path.join(skillsDir, entry.name);
+        const skillFile = path.join(dir, "SKILL.md");
+        try {
+            const stat = await fs.stat(skillFile);
+            if (stat.isFile()) {
+                result.push({ dir, skillFile });
+            }
+        }
+        catch {
+            // ignore dirs without SKILL.md
+        }
+    }
+    return result;
+}

package/dist/skills/index.js

@@ -0,0 +1,7 @@
+export * from "./types.js";
+export * from "./paths.js";
+export * from "./parse.js";
+export * from "./discover.js";
+export * from "./registry.js";
+export * from "./match.js";
+export * from "./prompt.js";

package/dist/skills/match.js

@@ -0,0 +1,59 @@
+function tokenize(input) {
+    return input
+        .toLowerCase()
+        .split(/[\s,，。.!?！？:：;；"'`“”‘’（）(){}\[\]<>\/\\|+-]+/g)
+        .map((x) => x.trim())
+        .filter(Boolean);
+}
+function includesAny(text, keywords) {
+    const lower = text.toLowerCase();
+    return keywords.some((k) => lower.includes(k.toLowerCase()));
+}
+export function matchSkills(input, skills) {
+    const q = input.trim().toLowerCase();
+    if (!q)
+        return { matched: [] };
+    const tokens = tokenize(q);
+    const scored = [];
+    for (const skill of skills) {
+        let score = 0;
+        const name = skill.name.toLowerCase();
+        const desc = skill.description.toLowerCase();
+        const tags = skill.tags.map((t) => t.toLowerCase());
+        if (q.includes(name))
+            score += 10;
+        if (tokens.includes(name))
+            score += 8;
+        for (const tag of tags) {
+            if (q.includes(tag))
+                score += 6;
+            if (tokens.includes(tag))
+                score += 4;
+        }
+        const descKeywords = desc
+            .split(/[\s,，。.!?！？:：;；"'`“”‘’（）(){}\[\]<>\/\\|+-]+/g)
+            .map((x) => x.trim())
+            .filter((x) => x.length >= 3);
+        let descHitCount = 0;
+        for (const token of tokens) {
+            if (descKeywords.includes(token)) {
+                descHitCount += 1;
+            }
+        }
+        score += Math.min(descHitCount, 3);
+        // 特判：pdf skill
+        if (name === "pdf") {
+            if (includesAny(q, [".pdf", "pdf", "ocr", "表单", "合并pdf", "拆分pdf", "提取pdf"])) {
+                score += 8;
+            }
+        }
+        if (score > 0) {
+            scored.push({ skill, score });
+        }
+    }
+    scored.sort((a, b) => b.score - a.score);
+    return {
+        matched: scored.slice(0, 3).map((x) => x.skill),
+        reason: scored.length ? `matched ${scored.length} skill(s)` : undefined,
+    };
+}

package/dist/skills/parse.js

@@ -0,0 +1,8 @@
+import matter from "gray-matter";
+export function parseSkillFile(content) {
+    const parsed = matter(content);
+    return {
+        meta: (parsed.data ?? {}),
+        body: parsed.content.trim(),
+    };
+}

package/dist/skills/paths.js

@@ -0,0 +1,14 @@
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs/promises";
+export function getYuanClawHomeDir() {
+    return path.join(os.homedir(), ".yuan-claw");
+}
+export function getSkillsDir() {
+    return path.join(getYuanClawHomeDir(), "skills");
+}
+export async function ensureSkillsDir() {
+    const dir = getSkillsDir();
+    await fs.mkdir(dir, { recursive: true });
+    return dir;
+}

package/dist/skills/prompt.js

@@ -0,0 +1,26 @@
+export function buildSkillsPrompt(skills) {
+    if (!skills.length)
+        return "";
+    const parts = skills.map((skill) => {
+        const lines = [];
+        lines.push(`Skill Name: ${skill.name}`);
+        if (skill.description)
+            lines.push(`Description: ${skill.description}`);
+        if (skill.tags.length)
+            lines.push(`Tags: ${skill.tags.join(", ")}`);
+        if (skill.license)
+            lines.push(`License: ${skill.license}`);
+        lines.push("");
+        lines.push("[SKILL CONTENT BEGIN]");
+        lines.push(skill.body);
+        lines.push("[SKILL CONTENT END]");
+        return lines.join("\n");
+    });
+    return [
+        "You have access to the following local skills.",
+        "Use them when they are relevant to the user's request.",
+        "If a skill contains procedures, best practices, or tool suggestions, follow them.",
+        "",
+        ...parts,
+    ].join("\n");
+}

package/dist/skills/registry.js

@@ -0,0 +1,43 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { discoverSkillDirs } from "./discover.js";
+import { parseSkillFile } from "./parse.js";
+function normalizeTags(input) {
+    if (!Array.isArray(input))
+        return [];
+    return input
+        .filter((x) => typeof x === "string")
+        .map((x) => x.trim())
+        .filter(Boolean);
+}
+function fallbackNameFromDir(dir) {
+    return path.basename(dir);
+}
+export async function loadSkills() {
+    const discovered = await discoverSkillDirs();
+    const skills = [];
+    for (const item of discovered) {
+        try {
+            const raw = await fs.readFile(item.skillFile, "utf8");
+            const { meta, body } = parseSkillFile(raw);
+            const name = (meta.name?.trim() || fallbackNameFromDir(item.dir)).trim();
+            const description = (meta.description?.trim() || "").trim();
+            skills.push({
+                name,
+                description,
+                license: meta.license?.trim(),
+                version: meta.version?.trim(),
+                tags: normalizeTags(meta.tags),
+                dir: item.dir,
+                skillFile: item.skillFile,
+                body,
+                raw,
+            });
+        }
+        catch {
+            // ignore invalid skill files
+        }
+    }
+    skills.sort((a, b) => a.name.localeCompare(b.name));
+    return skills;
+}

package/dist/skills/runtime.js

@@ -0,0 +1,19 @@
+import { loadSkills } from "./registry.js";
+import { matchSkills } from "./match.js";
+import { buildSkillsPrompt } from "./prompt.js";
+export class SkillsRuntime {
+    skills = [];
+    async reload() {
+        this.skills = await loadSkills();
+    }
+    list() {
+        return this.skills;
+    }
+    match(input) {
+        return matchSkills(input, this.skills).matched;
+    }
+    buildPromptForInput(input) {
+        const matched = this.match(input);
+        return buildSkillsPrompt(matched);
+    }
+}

package/dist/skills/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jiangyuan1209/yuan-claw",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "A local CLI agent with tools, search, and interactive approval.",
   "type": "module",
   "bin": {
@@ -27,6 +27,7 @@
     "@clack/prompts": "^1.3.0",
     "@mozilla/readability": "^0.6.0",
     "dotenv": "^17.4.2",
+    "gray-matter": "^4.0.3",
     "jsdom": "^29.0.2",
     "openai": "^4.56.0",
     "zod": "^3.23.8"
@@ -37,4 +38,4 @@
     "tsx": "^4.19.1",
     "typescript": "^5.6.2"
   }
-}
+}