技能培养者

工程开发 社区

技能解读

当前原文的自动摘译,尚未人工审校。

何时使用

当用户想要执行以下操作时,请使用此技能: 创建全新技能 将重复提示或工作流程转变为可重用技能 改进现有技能的结构、触发器描述或捆绑资源 为技能添加真实的评估提示

首先决定:技能还是工具?

当能力主要是指令、shell 命令和现有工具时,选择一项技能。当任务需要时选择一个工具: 每次都严格的运行时行为 内置身份验证或 API 密钥处理 二进制或流数据处理

澄清合同

如果缺少重要细节,则仅询问所需的最小答案集: 技能名称:必须是 kebab-case 能力:技能应帮助代理执行哪些操作 触发上下文:应激活哪些类型的用户请求 输出:技能应生成哪些文件或结果

目录布局

除非任务明显需要更少,否则使用此布局:

范围规则

每个技能必须位于自己的目录中,并且目录名称必须与kebab-case中的技能名称完全匹配。优先选择用户全局路径:~/.flocks/plugins/skills/<name>/SKILL.md不要将用户创建的技能写入.flocks/skills/;该位置用于内置技能,而不是用户/项目编写的插件技能 不要将技能文件分散到 docs/、tests/ 或临时输出文件夹中

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
工程开发
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@AgentFlocks · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
需简单配置
是否需要外部接口密钥
需要 · Vendor-specific
兼容的系统
未声明(默认跨平台)
运行环境要求
Python
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 命令执行
  • 读取环境变量
网络行为
允许外网请求
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# Skill Builder

Create a reusable skill directory, not just a loose markdown file. Start with the smallest structure that can work: `SKILL.md` first, then add `references/`, `scripts/`, `assets/`, or `evals/evals.json` only when they reduce repeated work or keep the prompt lean.

## When to Use

Use this skill when the user wants to:

- create a brand new skill
- turn a repeated prompt or workflow into a reusable skill
- improve an existing skill's structure, trigger description, or bundled resources
- add realistic eval prompts for a skill
- package a repo-local skill so it can be reused elsewhere

## Decide First: Skill or Tool?

Choose a **skill** when the capability is mostly instructions, shell commands, and existing tools.

Choose a **tool** instead when the task needs:

- strict runtime behavior every time
- built-in auth or API-key handling
- binary or streaming data handling
- a new system integration that should not depend on prompt interpretation

If the task is really a tool problem, say so early and switch to tool creation instead of forcing a skill.

## Clarify the Contract

If important details are missing, ask only for the smallest set of answers needed:

1. **Skill name**: must be `kebab-case`
2. **Capability**: what the skill should help the agent do
3. **Triggering context**: what kinds of user requests should activate it
4. **Outputs**: what files or results the skill should produce
5. **Testing**: whether to add eval prompts now

If the request is mostly clear, propose sensible defaults and keep moving.

## Directory Layout

Use this layout unless the task clearly needs less:

```text
<skill-root>/
├── SKILL.md
├── evals/
│   └── evals.json          # optional
├── references/            # optional
├── scripts/               # optional
└── assets/                # optional
```

### Scope Rules

- Each skill must live in its own directory, and the directory name must exactly match the skill name in `kebab-case`
- Prefer the user-global path: `~/.flocks/plugins/skills/<name>/SKILL.md`
- Do not write user-created skills to `.flocks/skills/`; that location is for built-in skills, not user/project-authored plugin skills
- Do not scatter skill files into `docs/`, `tests/`, or ad hoc output folders

## Build Workflow

### 1. Capture the Real Intent

Before writing the file, pin down:

- the user problem the skill solves
- the user language that should trigger the skill
- the expected output format
- whether the skill needs helper scripts, references, env vars, or config

When converting an existing workflow into a skill, extract the process from the conversation or nearby files instead of asking the user to repeat everything.

### 2. Inspect Nearby Examples

Read one or two similar skills in the current repo and reuse the local conventions for:

- frontmatter tone
- section naming
- path conventions
- validation style

Do not copy text blindly. Reuse structure, not wording.

### 3. Draft the Frontmatter

At minimum, every skill needs:

```yaml
---
name: my-skill
description: What it does and when to use it.
---
```

### 4. Write the Description for Triggering

The description is the main trigger. Make it slightly "pushy" instead of passive.

Good descriptions include both:

- **what the skill does**
- **when it should be used**

Prefer outcomes over internals.

```yaml
# Better
description: Create or improve reusable documentation skills. Use whenever the user asks to turn a repeated docs workflow into a skill, generate a SKILL.md, or add references and evals for documentation automation.
```

Avoid descriptions that only say "this skill helps manage skills" without any trigger hints.

### 5. Write the Body with Progressive Disclosure

Keep `SKILL.md` focused and easy to execute. A good default shape is:

1. what the skill does
2. when to use it
3. the minimum workflow to follow
4. pitfalls and validation
5. references to deeper files only when needed

Suggested sections:

- `## When to Use`
- `## Quick Start`
- `## Workflow` or `## Procedure`
- `## Pitfalls`
- `## Verification`

If the body starts getting long, move stable detail into `references/` and point to it explicitly. If the skill needs deterministic parsing or repeated transformations, add a helper under `scripts/` instead of asking the model to rewrite the same logic each time.

### 6. Prefer Simple Dependencies

Follow the guidance:

- prefer shell, Python stdlib, and existing tools first
- avoid adding dependencies unless they clearly reduce repeated work
- if setup is required, document it plainly in the skill

Do not create helper scripts "just in case".

### 7. Add Eval Prompts When Useful

If the skill has verifiable behavior, file outputs, or a repeatable workflow, create `evals/evals.json` with 2-3 realistic prompts.

Use prompts that sound like a real user, not abstract benchmark text.

```json
{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "Create a new skill for X with Y constraints.",
      "expected_output": "A valid skill directory with a strong description and the right files.",
      "files": []
    }
  ]
}
```

If the skill is highly subjective and the user does not want evals, skipping them is acceptable, but say that choice explicitly.

### 8. Verify Before Finishing

Before you report success:

- confirm the directory name matches the skill name
- confirm `name` is valid `kebab-case`
- confirm the description is strong enough to trigger
- confirm every referenced file actually exists
- confirm the file layout matches the chosen scope
- keep the skill lean; move bulky material to `references/` when needed

When working inside this repository, prefer at least one concrete verification step:

```bash
uv run python - <<'PY'
import asyncio
from flocks.skill.skill import Skill

async def main():
    skill = await Skill.get("my-skill")
    assert skill is not None
    print(skill.name, skill.source, skill.location)

asyncio.run(main())
PY
```

If the repo already has skill-related tests, add or update a focused test rather than relying only on a manual check.

## Output Checklist

When you finish, report:

- created or updated files
- chosen scope: `project` or `user`
- the trigger-rich description you encoded
- any skipped extras such as evals or scripts, and why

## Constraints

- Prefer the simplest viable skill.
- Do not add extra abstractions without clear reuse.
- Preserve the original skill name when editing an existing skill unless the user explicitly asks to rename it.
- Explain why steps matter instead of filling the skill with rigid commands.
- Keep the main skill body reasonably short; use `references/` and `scripts/` for overflow.

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。