foliko 2.0.11 → 2.0.13

package/skills/find-skills/SKILL.md

@@ -1,133 +1,133 @@
----
-name: find-skills
-description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
----
-
-# Find Skills
-
-This skill helps you discover and install skills from the open agent skills ecosystem.
-
-## When to Use This Skill
-
-Use this skill when the user:
-
-- Asks "how do I do X" where X might be a common task with an existing skill
-- Says "find a skill for X" or "is there a skill for X"
-- Asks "can you do X" where X is a specialized capability
-- Expresses interest in extending agent capabilities
-- Wants to search for tools, templates, or workflows
-- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
-
-## What is the Skills CLI?
-
-The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
-
-**Key commands:**
-
-- `npx skills find [query]` - Search for skills interactively or by keyword
-- `npx skills add <package>` - Install a skill from GitHub or other sources
-- `npx skills check` - Check for skill updates
-- `npx skills update` - Update all installed skills
-
-**Browse skills at:** https://skills.sh/
-
-## How to Help Users Find Skills
-
-### Step 1: Understand What They Need
-
-When a user asks for help with something, identify:
-
-1. The domain (e.g., React, testing, design, deployment)
-2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
-3. Whether this is a common enough task that a skill likely exists
-
-### Step 2: Search for Skills
-
-Run the find command with a relevant query:
-
-```bash
-npx skills find [query]
-```
-
-For example:
-
-- User asks "how do I make my React app faster?" → `npx skills find react performance`
-- User asks "can you help me with PR reviews?" → `npx skills find pr review`
-- User asks "I need to create a changelog" → `npx skills find changelog`
-
-The command will return results like:
-
-```
-Install with npx skills add <owner/repo@skill>
-
-vercel-labs/agent-skills@vercel-react-best-practices
-└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
-```
-
-### Step 3: Present Options to the User
-
-When you find relevant skills, present them to the user with:
-
-1. The skill name and what it does
-2. The install command they can run
-3. A link to learn more at skills.sh
-
-Example response:
-
-```
-I found a skill that might help! The "vercel-react-best-practices" skill provides
-React and Next.js performance optimization guidelines from Vercel Engineering.
-
-To install it:
-npx skills add vercel-labs/agent-skills@vercel-react-best-practices
-
-Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
-```
-
-### Step 4: Offer to Install
-
-If the user wants to proceed, you can install the skill for them:
-
-```bash
-npx skills add <owner/repo@skill> -g -y
-```
-
-The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
-
-## Common Skill Categories
-
-When searching, consider these common categories:
-
-| Category        | Example Queries                          |
-| --------------- | ---------------------------------------- |
-| Web Development | react, nextjs, typescript, css, tailwind |
-| Testing         | testing, jest, playwright, e2e           |
-| DevOps          | deploy, docker, kubernetes, ci-cd        |
-| Documentation   | docs, readme, changelog, api-docs        |
-| Code Quality    | review, lint, refactor, best-practices   |
-| Design          | ui, ux, design-system, accessibility     |
-| Productivity    | workflow, automation, git                |
-
-## Tips for Effective Searches
-
-1. **Use specific keywords**: "react testing" is better than just "testing"
-2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
-3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
-
-## When No Skills Are Found
-
-If no relevant skills exist:
-
-1. Acknowledge that no existing skill was found
-2. Offer to help with the task directly using your general capabilities
-3. Suggest the user could create their own skill with `npx skills init`
-
-Example:
-
-```
-I searched for skills related to "xyz" but didn't find any matches.
-I can still help you with this task directly! Would you like me to proceed?
-
-If this is something you do often, you could create your own skill:
-npx skills init my-xyz-skill
-```
+---
+name: find-skills
+description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
+---
+
+# Find Skills
+
+This skill helps you discover and install skills from the open agent skills ecosystem.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Asks "how do I do X" where X might be a common task with an existing skill
+- Says "find a skill for X" or "is there a skill for X"
+- Asks "can you do X" where X is a specialized capability
+- Expresses interest in extending agent capabilities
+- Wants to search for tools, templates, or workflows
+- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
+
+## What is the Skills CLI?
+
+The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
+
+**Key commands:**
+
+- `npx skills find [query]` - Search for skills interactively or by keyword
+- `npx skills add <package>` - Install a skill from GitHub or other sources
+- `npx skills check` - Check for skill updates
+- `npx skills update` - Update all installed skills
+
+**Browse skills at:** https://skills.sh/
+
+## How to Help Users Find Skills
+
+### Step 1: Understand What They Need
+
+When a user asks for help with something, identify:
+
+1. The domain (e.g., React, testing, design, deployment)
+2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
+3. Whether this is a common enough task that a skill likely exists
+
+### Step 2: Search for Skills
+
+Run the find command with a relevant query:
+
+```bash
+npx skills find [query]
+```
+
+For example:
+
+- User asks "how do I make my React app faster?" → `npx skills find react performance`
+- User asks "can you help me with PR reviews?" → `npx skills find pr review`
+- User asks "I need to create a changelog" → `npx skills find changelog`
+
+The command will return results like:
+
+```
+Install with npx skills add <owner/repo@skill>
+
+vercel-labs/agent-skills@vercel-react-best-practices
+└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 3: Present Options to the User
+
+When you find relevant skills, present them to the user with:
+
+1. The skill name and what it does
+2. The install command they can run
+3. A link to learn more at skills.sh
+
+Example response:
+
+```
+I found a skill that might help! The "vercel-react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+
+To install it:
+npx skills add vercel-labs/agent-skills@vercel-react-best-practices
+
+Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 4: Offer to Install
+
+If the user wants to proceed, you can install the skill for them:
+
+```bash
+npx skills add <owner/repo@skill> -g -y
+```
+
+The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
+
+## Common Skill Categories
+
+When searching, consider these common categories:
+
+| Category        | Example Queries                          |
+| --------------- | ---------------------------------------- |
+| Web Development | react, nextjs, typescript, css, tailwind |
+| Testing         | testing, jest, playwright, e2e           |
+| DevOps          | deploy, docker, kubernetes, ci-cd        |
+| Documentation   | docs, readme, changelog, api-docs        |
+| Code Quality    | review, lint, refactor, best-practices   |
+| Design          | ui, ux, design-system, accessibility     |
+| Productivity    | workflow, automation, git                |
+
+## Tips for Effective Searches
+
+1. **Use specific keywords**: "react testing" is better than just "testing"
+2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
+3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
+
+## When No Skills Are Found
+
+If no relevant skills exist:
+
+1. Acknowledge that no existing skill was found
+2. Offer to help with the task directly using your general capabilities
+3. Suggest the user could create their own skill with `npx skills init`
+
+Example:
+
+```
+I searched for skills related to "xyz" but didn't find any matches.
+I can still help you with this task directly! Would you like me to proceed?
+
+If this is something you do often, you could create your own skill:
+npx skills init my-xyz-skill
+```

package/skills/skill-guide/SKILL.md

@@ -100,24 +100,24 @@ frontmatter 之后是技能的正文内容，支持 Markdown 格式，包含：
 打招呼命令。
 
 **参数：**
-- `args`（可选）：名字，如 `/my-skill:greet Alice`
+- `name`（可选）：名字，默认 "World"
+- `lang`（可选）：语言，如 "en"，默认 "zh"
 
 **示例：**
 - `/my-skill:greet` → "Hello World"
-- `/my-skill:greet Alice` → "Hello Alice"
+- `/my-skill:greet {"name":"Alice"}` → "Hello Alice"
 
 ### /my-skill:split
 
 切割会话命令。
 
 **参数：**
-- `-t, --tokens <value>`：保留 token 数（默认 4000）
-- `-k, --keep-recent <value>`：保留最近 token（默认 1000）
-- `[args...]`：位置参数
+- `tokens`（可选）：保留 token 数，默认 4000
+- `keepRecent`（可选）：保留最近 token，默认 1000
 
 **示例：**
 - `/my-skill:split` → 使用默认参数
-- `/my-skill:split -t 8000 extra` → tokens=8000，extra 作为位置参数
+- `/my-skill:split {"tokens":8000}` → tokens=8000
 ```
 
 ### index.js 格式
@@ -127,23 +127,26 @@ module.exports = [
   {
     name: 'greet',           // 命令名
     description: '打招呼',   // 命令描述
+    options: [
+      { flags: '-n, --name <value>', description: '名字', defaultValue: 'World' },
+      { flags: '-l, --lang <value>', description: '语言', defaultValue: 'zh' }
+    ],
     execute: async (args, ctx) => {
-      // args: 传入的参数（字符串）
+      // args: 解析后的结构化对象，如 { name: "Alice", lang: "en" }
       // ctx: 上下文对象 { sessionId, agent, framework }
-      return 'Hello ' + (args || 'World');
+      return `Hello ${args.name || 'World'}`;
     }
   },
   {
     name: 'split',
     description: '切割会话',
-    // 简洁方式：定义选项数组，自动使用 Commander.js 解析
     options: [
-      { flags: '-t, --tokens <value>', description: '保留 token 数', defaultValue: '4000' },
-      { flags: '-k, --keep-recent <value>', description: '保留最近 token', defaultValue: '1000' }
+      { flags: '-t, --tokens <value>', type: 'number', description: '保留 token 数', defaultValue: 4000 },
+      { flags: '-k, --keep-recent <value>', type: 'number', description: '保留最近 token', defaultValue: 1000 }
     ],
-    execute: async (parsedArgs, ctx) => {
-      // parsedArgs: { tokens: "4000", keepRecent: "1000", args: [...] }
-      return `Split: tokens=${parsedArgs.tokens}`;
+    execute: async (args, ctx) => {
+      // args: { tokens: 4000, keepRecent: 1000 }
+      return `Split: tokens=${args.tokens}`;
     }
   },
   {
@@ -156,11 +159,12 @@ module.exports = [
 ];
 ```
 
-**参数解析说明：**
+**参数类型说明：**
 
-- 不提供 `options` 时，`args` 是原始参数字符串
-- 提供 `options` 数组时，自动使用 Commander.js 解析，`execute` 收到解析后的对象
-- 对象格式：`{ tokens, keepRecent, args: [...] }`
+- `options[].type`：可选，声明参数类型 (`String` | `Number` | `Boolean` | `Array` | `Object`)，帮助 LLM 理解参数格式
+- 不提供 `options` 时，`args` 是空对象 `{}`
+- 提供 `options` 数组时，`execute` 收到解析后的结构化对象
+- 对象格式：`{ name, lang, tokens, keepRecent, ... }`（camelCase，匹配 flag 名称）
 
 ### 命令调用方式
 
@@ -182,11 +186,11 @@ module.exports = [
 // 1. 先查询命令参数
 ext_skill({ plugin: "skill:<技能名>" })
 
-// 2. 用命令行字符串调用
+// 2. 用结构化参数调用
 ext_call({
   plugin: "skill:<技能名>",
   tool: "<commandname>",
-  args: { command: "-n Alice -l en" }
+  args: { name: "Alice", lang: "en" }
 });
 ```
 
@@ -196,30 +200,30 @@ ext_call({
 |------|------|------|
 | `plugin` | string | 固定为 `"skill:<技能名>"`，如 `skill:test-skill` |
 | `tool` | string | 命令名（不带技能前缀），如 `greet` |
-| `args` | object | 固定为 `{ command: "命令行字符串" }` |
+| `args` | object | 结构化参数对象，字段名对应 `options` 中的参数名（camelCase） |
 
 **示例：**
 
 ```javascript
-// 调用 test-skill 的 greet 命令
+// 调用 test-skill 的 greet 命令（带参数）
 ext_call({
   plugin: "skill:test-skill",
   tool: "greet",
-  args: { command: "-n Alice" }
+  args: { name: "Alice", lang: "en" }
 });
 
-// 调用 test-skill 的 greet 命令，带可选 lang
+// 调用 test-skill 的 greet 命令（使用默认参数）
 ext_call({
   plugin: "skill:test-skill",
   tool: "greet",
-  args: { command: "-n Alice -l en" }
+  args: {}
 });
 
-// 调用 test-skill 的 echo 命令
+// 调用 test-skill 的 split 命令
 ext_call({
   plugin: "skill:test-skill",
-  tool: "echo",
-  args: { command: "Hello World" }
+  tool: "split",
+  args: { tokens: 8000 }
 });
 ```
 
@@ -234,8 +238,23 @@ ext_call({
 
 ```javascript
 module.exports = [
-  { name: 'greet', description: '打招呼', execute: async (args) => 'Hello ' + (args || 'World') },
-  { name: 'echo', description: '回声命令', execute: async (args) => 'Echo: ' + args }
+  {
+    name: 'greet',
+    description: '打招呼',
+    options: [
+      { flags: '-n, --name <value>', description: '名字', defaultValue: 'World' },
+      { flags: '-l, --lang <value>', description: '语言', defaultValue: 'zh' }
+    ],
+    execute: async (args) => `Hello ${args.name || 'World'}`
+  },
+  {
+    name: 'echo',
+    description: '回声命令',
+    options: [
+      { flags: '-t, --text <value>', description: '回显文本', required: true }
+    ],
+    execute: async (args) => 'Echo: ' + args.text
+  }
 ];
 ```
 
@@ -249,21 +268,22 @@ module.exports = [
 打招呼命令。
 
 **参数：**
-- `args`（可选）：名字
+- `name`（可选）：名字，默认 "World"
+- `lang`（可选）：语言，默认 "zh"
 
 **示例：**
 - `/test-skill:greet` → "Hello World"
-- `/test-skill:greet Alice` → "Hello Alice"
+- `/test-skill:greet {"name":"Alice"}` → "Hello Alice"
 
 ### /test-skill:echo
 
 回声命令，将输入原样返回。
 
 **参数：**
-- `args`：要回显的文本
+- `text`（必填）：要回显的文本
 
 **示例：**
-- `/test-skill:echo Hello` → "Echo: Hello"
+- `/test-skill:echo {"text":"Hello"}` → "Echo: Hello"
 ```
 
 ### 自动注册
@@ -338,23 +358,26 @@ module.exports = [
   {
     name: 'greet',           // 命令名
     description: '打招呼',   // 命令描述
+    options: [
+      { flags: '-n, --name <value>', description: '名字', defaultValue: 'World' },
+      { flags: '-l, --lang <value>', description: '语言', defaultValue: 'zh' }
+    ],
     execute: async (args, ctx) => {
-      // args: 传入的参数（字符串）
+      // args: 解析后的结构化对象，如 { name: "Alice", lang: "en" }
       // ctx: 上下文对象 { sessionId, agent, framework }
-      return 'Hello ' + (args || 'World');
+      return `Hello ${args.name || 'World'}`;
     }
   },
   {
     name: 'split',
     description: '切割会话',
-    // 简洁方式：定义选项数组，自动使用 Commander.js 解析
     options: [
-      { flags: '-t, --tokens <value>', description: '保留 token 数', defaultValue: '4000' },
-      { flags: '-k, --keep-recent <value>', description: '保留最近 token', defaultValue: '1000' }
+      { flags: '-t, --tokens <value>', type: 'number', description: '保留 token 数', defaultValue: 4000 },
+      { flags: '-k, --keep-recent <value>', type: 'number', description: '保留最近 token', defaultValue: 1000 }
     ],
-    execute: async (parsedArgs, ctx) => {
-      // parsedArgs: { tokens: "4000", keepRecent: "1000", args: [...] }
-      return `Split: tokens=${parsedArgs.tokens}`;
+    execute: async (args, ctx) => {
+      // args: { tokens: 4000, keepRecent: 1000 }
+      return `Split: tokens=${args.tokens}`;
     }
   },
   {
@@ -367,11 +390,12 @@ module.exports = [
 ];
 ```
 
-**参数解析说明：**
+**参数类型说明：**
 
-- 不提供 `options` 时，`args` 是原始参数字符串
-- 提供 `options` 数组时，自动使用 Commander.js 解析，`execute` 收到解析后的对象
-- 对象格式：`{ tokens, keepRecent, args: [...] }`
+- `options[].type`：可选，声明参数类型 (`String` | `Number` | `Boolean` | `Array` | `Object`)，帮助 LLM 理解参数格式
+- 不提供 `options` 时，`args` 是空对象 `{}`
+- 提供 `options` 数组时，`execute` 收到解析后的结构化对象
+- 对象格式：`{ name, lang, tokens, keepRecent, ... }`（camelCase，匹配 flag 名称）
 
 ### 命令调用方式
 
@@ -393,11 +417,11 @@ module.exports = [
 // 1. 先查询命令参数
 ext_skill({ plugin: "skill:<技能名>" })
 
-// 2. 用命令行字符串调用
+// 2. 用结构化参数调用
 ext_call({
   plugin: "skill:<技能名>",
   tool: "<commandname>",
-  args: { command: "-n Alice -l en" }
+  args: { name: "Alice", lang: "en" }
 });
 ```
 
@@ -407,30 +431,30 @@ ext_call({
 |------|------|------|
 | `plugin` | string | 固定为 `"skill:<技能名>"`，如 `skill:test-skill` |
 | `tool` | string | 命令名（不带技能前缀），如 `greet` |
-| `args` | object | 固定为 `{ command: "命令行字符串" }` |
+| `args` | object | 结构化参数对象，字段名对应 `options` 中的参数名（camelCase） |
 
 **示例：**
 
 ```javascript
-// 调用 test-skill 的 greet 命令
+// 调用 test-skill 的 greet 命令（带参数）
 ext_call({
   plugin: "skill:test-skill",
   tool: "greet",
-  args: { command: "-n Alice" }
+  args: { name: "Alice", lang: "en" }
 });
 
-// 调用 test-skill 的 greet 命令，带可选 lang
+// 调用 test-skill 的 greet 命令（使用默认参数）
 ext_call({
   plugin: "skill:test-skill",
   tool: "greet",
-  args: { command: "-n Alice -l en" }
+  args: {}
 });
 
-// 调用 test-skill 的 echo 命令
+// 调用 test-skill 的 split 命令
 ext_call({
   plugin: "skill:test-skill",
-  tool: "echo",
-  args: { command: "Hello World" }
+  tool: "split",
+  args: { tokens: 8000 }
 });
 ```
 
@@ -445,16 +469,31 @@ ext_call({
 
 ```javascript
 module.exports = [
-  { name: 'greet', description: '打招呼', execute: async (args) => 'Hello ' + (args || 'World') },
-  { name: 'echo', description: '回声命令', execute: async (args) => 'Echo: ' + args }
+  {
+    name: 'greet',
+    description: '打招呼',
+    options: [
+      { flags: '-n, --name <value>', description: '名字', defaultValue: 'World' },
+      { flags: '-l, --lang <value>', description: '语言', defaultValue: 'zh' }
+    ],
+    execute: async (args) => `Hello ${args.name || 'World'}`
+  },
+  {
+    name: 'echo',
+    description: '回声命令',
+    options: [
+      { flags: '-t, --text <value>', description: '回显文本', required: true }
+    ],
+    execute: async (args) => 'Echo: ' + args.text
+  }
 ];
 ```
 
 **使用方法：**
 
 - `/test-skill:greet` → 返回 "Hello World"
-- `/test-skill:greet Alice` → 返回 "Hello Alice"
-- `/test-skill:echo Hello` → 返回 "Echo: Hello"
+- `/test-skill:greet {"name":"Alice"}` → 返回 "Hello Alice"
+- `/test-skill:echo {"text":"Hello"}` → 返回 "Echo: Hello"
 
 ### 自动注册