技能作者
- 作者仓库星标 428
- 作者仓库 mellea
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @generative-computing · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
---
name: my-skill
description: >
Does X when Y. Use when asked to Z.
argument-hint: "[target] [--flag]"
compatibility: "Claude Code, IBM Bob"
metadata:
version: "2026-03-25"
capabilities: [bash, read_file, write_file]
---
# Skill Authoring Meta-Skill
Create new agent skills that work across Claude Code (CLI/IDE) and IBM Bob.
## Skill Location
Skills live under `.agents/skills/<name>/SKILL.md`.
Discovery configuration varies by tool:
- **Claude Code:** Add `"skillLocations": [".agents/skills"]` to `.claude/settings.json`.
Without this, Claude Code looks in `.claude/skills/` by default.
- **IBM Bob:** Discovers `.agents/skills/` natively per agentskills.io convention.
Both tools read the same `SKILL.md` format. Use the frontmatter schema below
to maximise compatibility.
## Workflow
1. **Name the skill** — kebab-case, max 64 chars (e.g. `api-tester`, `audit-markers`).
2. **Scaffold the directory:**
```
.agents/skills/<name>/
├── SKILL.md # Required — frontmatter + instructions
├── scripts/ # Optional — helper scripts
└── templates/ # Optional — output templates
```
3. **Write SKILL.md** — YAML frontmatter + markdown body (see schema below).
4. **Dry-run review** — mentally execute the skill against a realistic scenario
before finalising. Walk through the procedure on a concrete example (a real
file in the repo, not a hypothetical) and check for:
- **Scaling gaps:** Does the procedure work for 1 file AND 100 files? If the
skill accepts a directory or glob, it needs a triage strategy (e.g., "grep
first to find candidates, then deep-read only files with issues") — not
just "read every file fully."
- **Boundary ambiguity:** If the skill defines categories or classifications,
test the boundaries between adjacent categories with a real example. The
edges are where agents will disagree or ask the user. Sharpen definitions
until two agents reading the same test would classify it the same way.
- **Stale references:** If the skill describes project state ("this hook needs
to be added", "this marker is not yet registered"), verify those statements
are still true. Embed checks ("read conftest.py to confirm") rather than
assertions that rot.
- **Output format at scale:** Run the report template mentally against the
largest expected input. A per-function report for 5 files is fine; for 165
files it's unusable. Design output for the largest scope — summary table
first, per-item detail only where issues exist.
- **Format coverage:** If the skill operates on multiple input formats (e.g.,
`pytestmark` lists AND `# pytest:` comments), verify each format is
explicitly addressed in the procedure. Implicit coverage causes agents to
skip or guess.
- **Rigid rules:** If you wrote "always X" or "never Y", find the edge case
where the rule is wrong. Add the escape hatch. E.g., "per-function only"
should say "module-level is acceptable when every function qualifies."
5. **Validate:**
- Check the skill is discoverable: list files in `.agents/skills/`.
- Confirm no frontmatter warnings from the IDE.
- Verify the skill does not conflict with existing skills or `AGENTS.md`.
## SKILL.md Frontmatter Schema
Use only fields from the **cross-compatible** set to avoid IDE warnings.
### Cross-compatible fields (use these)
| Field | Type | Purpose |
|-------|------|---------|
| `name` | string | Kebab-case identifier. Becomes the `/slash-command`. Max 64 chars. |
| `description` | string | What the skill does and when to trigger it. Be specific — agents use this to decide whether to invoke the skill automatically. |
| `argument-hint` | string | Autocomplete hint. E.g. `"[file] [--dry-run]"`, `"[issue-number]"`. |
| `compatibility` | string | Which tools support this skill. E.g. `"Claude Code, IBM Bob"`. |
| `disable-model-invocation` | boolean | `true` = manual `/name` only, no auto-invocation. |
| `user-invocable` | boolean | `false` = hidden from `/` menu. Use for background knowledge skills. |
| `license` | string | SPDX identifier if publishing. E.g. `"Apache-2.0"`. |
| `metadata` | object | Free-form key-value pairs for tool-specific or custom fields. |
### Tool-specific fields (put under `metadata`)
These are useful but not universally supported — nest them under `metadata`:
```yaml
metadata:
version: "2026-03-25"
capabilities: [bash, read_file, write_file] # Bob/agentskills.io
```
Claude Code's `allowed-tools` and `context`/`agent` fields are recognised by
Claude Code but may trigger warnings in Bob's validator. If needed, add them
to `metadata` or accept the warnings.
### Example frontmatter
```yaml
---
name: my-skill
description: >
Does X when Y. Use when asked to Z.
argument-hint: "[target] [--flag]"
compatibility: "Claude Code, IBM Bob"
metadata:
version: "2026-03-25"
capabilities: [bash, read_file, write_file]
---
```
## SKILL.md Body Structure
After frontmatter, write clear markdown instructions the agent follows:
1. **Context section** — what the skill operates on, key reference files.
2. **Procedure** — numbered steps the agent follows. Be explicit about decisions and edge cases.
3. **Rules / constraints** — hard rules the agent must not break.
4. **Output format** — what the agent should produce (report, edits, summary).
### Guidelines
- **Be specific.** Vague instructions produce inconsistent results across models.
"Check if markers are correct" is worse than "Compare the test's assertions
to the qualitative decision rule in section 3."
- **Reference project files.** Point to docs, configs, and examples by relative
path so the agent can read them. E.g. "See `test/MARKERS_GUIDE.md` for the
full marker taxonomy."
- **Declare scope boundaries.** State what the skill does NOT do. E.g. "This
skill does not modify conftest.py — flag infrastructure issues as notes."
- **Use `$ARGUMENTS`** for user input. `$ARGUMENTS` is the full argument string;
`$1`, `$2` etc. are positional.
- **Keep SKILL.md under 500 lines.** Use supporting files for large reference
material (link to them from the body).
- **Portability:** use relative paths from the repo root, never absolute paths.
- **Formatting:** use YYYY-MM-DD for dates, 24-hour clock for times, metric units.
- **Design for variable scope.** If the skill can operate on a single file or an
entire directory, provide a triage strategy for the large case. Agents given
"audit everything" with no prioritisation will either read every file (slow)
or skip files (incomplete).
- **Sharpen category boundaries.** When defining classifications, the boundary
between adjacent categories causes the most disagreement. Add a "key
distinction from X" sentence for each pair of adjacent tiers.
- **Avoid temporal assertions.** Don't write "this conftest hook needs to be
added" — write "check whether conftest.py already has the hook." State that
goes stale silently is worse than no guidance at all.
- **Qualify absolutes.** "Always X" and "never Y" rules need escape hatches for
the common exception. E.g., "per-function only — unless every function in the
file qualifies, in which case module-level is acceptable."
章节与文件索引
按说明文件中的顺序排列。
技能地点
工作流程
SKILL.md Frontmatter 架构
交叉兼容字段(使用这些)
工具特定字段(置于元数据下)
文件/命令 -> .agents/skills/<name>/SKILL.md · "skillLocations": [".agents/skills"] · .claude/settings.json · .claude/skills/ · .agents/skills/ · api-tester · audit-markers · pytestmark
内容校验值 -> b3540c8824b2
当前原文的自动摘译,尚未人工审校。
技能地点
技能位于
.agents/skills/<name>/SKILL.md下。发现配置因工具而异:Claude 代码:将"skillLocations": [".agents/skills"]添加到.claude/settings.json。如果没有这个,克劳德代码默认会查找.claude/skills/。 IBM Bob:根据agentskills.io 约定原生发现.agents/skills/。工作流程
为技能命名 — kebab-case,最多 64 个字符(例如
api-tester、audit-markers)。搭建目录:编写 SKILL.md — YAML frontmatter + markdown body(参见下面的架构)。预演回顾——在最终确定之前,在脑海中根据现实场景执行技能。通过具体示例(真实的SKILL.md Frontmatter 架构
仅使用交叉兼容集中的字段以避免 IDE 警告。
交叉兼容字段(使用这些)
字段·类型·用途
name·字符串·Kebab 大小写标识符。成为/slash-command。最多 64 个字符。description· string · 该技能的作用以及何时触发。具体——代理使用它来决定是否自动调用该技能。argument-hint· 字符串 · 自动完成提示。例如"[file] [--dry-run]","[issue-number]"。compatibility· string · 哪些工具支持该技能。例如"Claude Code, IBM Bob"。工具特定字段(置于元数据下)
这些很有用,但并未得到普遍支持 - 将它们嵌套在
metadata下:Claude Code 的allowed-tools和context/agent字段可以被 Claude Code 识别,但可能会在 Bob 的验证器中触发警告。如果需要,请将它们添加到metadata或接受警告。