技能创造

其他 社区

技能解读

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

概述

按照代理技能规范创建一个新的工作区技能目录和SKILL.md文件。技能是.stencila/skills/下的目录,其中包含带有YAML frontmatter和Markdown正文的SKILL.md文件。技能是人工智能代理可重复使用的指令集。技能应该是独立的。不要依赖技能目录之外的文档或其他内容。如果技能需要存储库中其他位置或其他来源的支持材料,请将其复制、总结或摘录到技能自己的references/目录中的文件中,然后从SKILL.md链接到这些本地文件。

步骤

根据用户的请求确定技能名称 根据以下命名规则验证名称 解析最近的工作区技能目录:从当前目录向上查找包含 .stencila/ 的最近目录,或者如果不存在则使用存储库根目录 创建目录 <closest-workspace>/.stencila/skills/<name>/ 使用前文和说明编写 SKILL.md 文件 — 在 description 中包含激活关键字,以便代理可以将技能与用户请求相匹配

命名规则

技能名称必须为小写短横线:1–64 个字符 仅限小写字母数字字符和连字符(a-z、0-9、-) 不得以连字符开头或结尾 不得包含连续的连字符 (--)

技能.md 格式

该文件由两部分组成: --- 分隔符之间的 YAML frontmatter 包含代理说明的 Markdown 正文

必需的 frontmatter 字段

name — 技能名称(必须与目录名称匹配) description — 技能的用途以及何时使用(最多 1,024 个字符)。包括帮助客服人员决定是否激活该技能的特定关键字。

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

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

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

## Overview

Create a new workspace skill directory and `SKILL.md` file following the Agent Skills Specification. A skill is a directory under `.stencila/skills/` containing a `SKILL.md` file with YAML frontmatter and a Markdown body. Skills are reusable instruction sets for AI agents.

Skills should be self-contained. Do not rely on documentation or other content outside the skill directory. If the skill needs supporting material from elsewhere in the repository or from another source, copy it, summarize it, or excerpt it into files inside the skill's own `references/` directory, then link to those local files from `SKILL.md`.

## Steps

1. Determine the skill name from the user's request
2. Validate the name against the naming rules below
3. Resolve the closest workspace skill directory: walk up from the current directory to find the nearest directory containing `.stencila/`, or use the repository root if none exists
4. Create the directory `<closest-workspace>/.stencila/skills/<name>/`
5. Write the `SKILL.md` file with frontmatter and instructions — include activation keywords in the `description` so agents can match the skill to user requests
6. Add `keywords` to the frontmatter to improve discoverability and delegation accuracy — include terms reflecting likely user intents, artifacts, and domains
7. Replace placeholders such as `TODO` before considering the skill complete
8. If the skill depends on supporting guidance, examples, or specifications, create focused files in `references/` and put that material there rather than referring to files elsewhere in the repo
9. Optionally create `scripts/`, `references/`, or `assets/` subdirectories if the skill needs them
10. Validate the finished skill with `stencila skills validate <name>`, the skill directory path, or the `SKILL.md` path

When working from a nested directory in a repository, create the skill in the closest workspace's `.stencila/skills/` directory rather than creating a new `.stencila/` tree under the current subdirectory.

## Naming Rules

Skill names must be **lowercase kebab-case**:

- 1–64 characters
- Only lowercase alphanumeric characters and hyphens (`a-z`, `0-9`, `-`)
- Must not start or end with a hyphen
- Must not contain consecutive hyphens (`--`)
- Must match the parent directory name
- Pattern: `^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$`

By convention, names follow a `thing-activity` pattern describing the domain and action (e.g., `code-review`, `data-analysis`, `test-generation`).

Common corrections: `reviewCode` → `code-review`, `data_analysis` → `data-analysis`, `Test-Gen` → `test-gen`.

## SKILL.md Format

The file has two parts:

1. **YAML frontmatter** between `---` delimiters
2. **Markdown body** with instructions for the agent

### Required frontmatter fields

- `name` — the skill name (must match directory name)
- `description` — what the skill does and when to use it (max 1,024 characters). Include specific keywords that help agents decide whether to activate the skill.

### Optional frontmatter fields

- `license` — SPDX identifier or reference to a license file
- `compatibility` — environment requirements (max 500 characters)
- `allowed-tools` — space-delimited or comma-delimited list of pre-approved tools (e.g., `read_file grep shell` or `read_file, grep, shell, ask_user`).
- `keywords` — (Stencila extension) list of keywords or tags for discovery and routing. Use terms that reflect likely user intents, artifacts, and domains. Helps managers and selection systems find and rank this skill. Include both positive signals (what this skill does) and negative signals (what it doesn't do) as keywords.
- `metadata` — arbitrary key-value pairs (e.g., `author`, `version`)

## Template

Use this as a starting point:

```markdown
---
name: <skill-name>
description: <Clear description including keywords that help agents match this skill to user requests. Do not leave placeholders such as TODO. Max 1,024 characters.>
keywords:
  - <keyword1>
  - <keyword2>
# license: MIT
# allowed-tools: read_file grep shell
# metadata:
#   author: <name>
#   version: 0.1.0
---

## Steps

1. <First step>
2. <Second step>
3. <Third step>

## Examples

Input: <describe expected input>

Output: <describe expected output>

## Edge Cases

- <Common pitfall and how to handle it>
```

## Directory Structure

Each skill gets its own subdirectory. Only `SKILL.md` is required:

```
.stencila/skills/
  <skill-name>/
    SKILL.md              # Required — frontmatter + instructions
    scripts/              # Optional — executable code
    references/           # Optional — additional documentation
    assets/               # Optional — static resources
```

Use `scripts/` for executable code, `references/` for detailed docs loaded on demand, and `assets/` for templates and data files. Reference them from `SKILL.md` using relative paths.

Do not point `SKILL.md` at repository documentation, specifications, or other files outside the skill directory. When outside material is necessary, prefer adding a concise summary or excerpt under `references/` instead of copying a large document verbatim. Keep individual reference files focused so agents can load only the minimum context needed.

## Choosing `allowed-tools`

Only include tools the skill genuinely needs; prefer the minimal set.

| Tool                       | Use for                                          | Include when                                                                |
| -------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------- |
| `read_file`                | Read existing files                              | The skill needs to inspect repository or workspace content                  |
| `write_file`               | Create new files or overwrite whole files        | The skill creates files from scratch                                        |
| `apply_patch`, `edit_file` | Modify existing files in place                   | The skill updates existing files; some models prefer one or the other       |
| `grep`                     | Search file contents                             | The skill needs to find patterns, symbols, or references                    |
| `glob`                     | Find files by pattern                            | The skill needs to discover files or directories                            |
| `web_fetch`                | Fetch and save web content locally               | The skill needs to retrieve web pages or external documentation for review or summarization |
| `shell`                    | Run commands                                     | The skill needs validation, formatting, tests, or other command-line checks |
| `ask_user`                 | Request clarification, confirmation, or approval | The skill may need user feedback before proceeding                          |

## Writing Guidelines

- Keep the body under 500 lines / 5,000 tokens
- Use step-by-step numbered lists — easy for models to follow
- Include input/output examples
- Cover edge cases and common pitfalls
- Move detailed reference material to `references/` files
- Keep the skill self-contained: avoid links or instructions that depend on files outside the skill directory
- If external or repo-local guidance is needed, summarize or excerpt it into focused files under `references/`
- Do not leave placeholder frontmatter or body content such as `TODO`
- Write a description that is specific, not vague (e.g., "Analyze datasets and generate summary statistics. Use when working with CSV, Parquet, or database query results." not "Helps with data.")
- Keep `description` under 1,024 characters and `compatibility` under 500 characters

### Keeping skills workflow-agnostic

Skills must describe **generic domain competence with generic inputs and outputs**. They should work equally well when invoked by a user in a chat, by an agent acting alone, or by a workflow stage prompt. Workflow-specific concerns — context keys, route labels, `workflow_*` tool calls — belong in the workflow's stage prompts, not in skills.

Follow these rules:

- **Do not reference `workflow_get_context`, `workflow_set_context`, `workflow_set_route`, or `workflow_get_output`** in any skill. These are workflow orchestration tools. If a skill needs input data, declare it in a "Required Inputs" table and let the caller (user, agent prompt, or workflow stage prompt) supply it.
- **Do not define "Context Keys" or "Route Labels" tables** in skills. The workflow owns its data contract — which keys hold which values, and which labels control which branches. Skills should not know or care about that contract.
- **Do not reference workflow node names** (e.g., `RunTestsRed`, `CheckRemaining`) or specific workflow files. Skills should not know which workflow is calling them.
- **Declare inputs and outputs generically.** Use a "Required Inputs" table listing what the skill needs (with Required/Optional) and an "Outputs" table listing what it produces. Use domain-appropriate names (e.g., "Acceptance criteria", "Test files", "Recommendation") rather than context key names.
- **Use a single sentence to explain how inputs arrive.** After the inputs table, include: "When used standalone, these inputs come from the user or the agent's prompt. When used within a workflow, the workflow's stage prompt will specify how to obtain them." This one sentence bridges both use cases without coupling to either.
- **Mark plan/file fallbacks as standalone convenience.** If a skill falls back to reading from a well-known location (e.g., `.stencila/plans/`) when an input is missing, frame this as a convenience for standalone use: "attempt to infer from X as a standalone convenience. In workflow use, the stage prompt should provide this explicitly."

The workflow's stage prompts are the glue layer. A well-structured stage prompt follows this pattern:

1. **Read workflow state** — `workflow_get_context` / `workflow_get_output` calls
2. **Delegate to the skill** — pass the retrieved values as the skill's declared inputs
3. **Store the skill's outputs** — `workflow_set_context` with the workflow's chosen key names
4. **Route** — `workflow_set_route` with the workflow's chosen labels, mapped from the skill's domain outputs

This separation means skills stay reusable across workflows, agents can use skills without workflow infrastructure, and the workflow is the single source of truth for its own data contract.

## Edge Cases

- **Skill directory already exists**: Ask the user whether to overwrite, merge, or abort before modifying an existing skill. Never silently overwrite.
- **Name mismatch**: If the user provides a name that doesn't match kebab-case rules, suggest a corrected version rather than failing silently.
- **Nested workspaces**: If multiple `.stencila/` directories exist in the ancestor chain, use the nearest one. Do not create a duplicate `.stencila/skills/` tree.
- **Empty or placeholder content**: Do not consider the skill complete if any `TODO`, `<placeholder>`, or empty sections remain in the final `SKILL.md`.
- **External dependencies in documentation**: If instructions refer to docs or files outside the skill directory, move the required content into focused files under `references/` and update `SKILL.md` to point only to those local copies, summaries, or excerpts.

## Validation

Before finishing, validate the skill:

```sh
# By skill name
stencila skills validate <skill-name>

# By directory path
stencila skills validate .stencila/skills/<skill-name>

# By SKILL.md path
stencila skills validate .stencila/skills/<skill-name>/SKILL.md
```

Validation should pass before you report the skill as complete.

讨论

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