Evan HuandClaude Opus 4.6
6c0faf06ef
Standardize on Claude Code's SKILL.md format as every skill's source of truth. skill.toml becomes an optional metadata layer for runtime, input schema, and versioning — never for the prompt body. - validate.py: require SKILL.md in every skill dir; when skill.toml also exists, cross-check name/description consistency to prevent drift - Add SKILL.md to the two custom-skill examples - Move the meeting-agenda prompt body out of skill.toml into SKILL.md - Rewrite skills/README.md to document the md-first, toml-as-metadata convention Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
89 lines
2.9 KiB
Markdown
89 lines
2.9 KiB
Markdown
# Skills
|
|
|
|
Reusable skill definitions for LibreFang agents. A skill is either a prompt
|
|
template or a code script that an agent can invoke to perform a specific task.
|
|
|
|
## File Convention
|
|
|
|
Every skill directory **must** contain a `SKILL.md` (the entry point).
|
|
A `skill.toml` is **optional** and only needed for structured metadata that
|
|
does not fit in Markdown frontmatter (runtime, input schema, version, tags).
|
|
|
|
```
|
|
skills/
|
|
├── docker/
|
|
│ └── SKILL.md # Prompt-only expert — no skill.toml needed
|
|
├── custom-skill-prompt/
|
|
│ ├── SKILL.md # Prompt body + name/description
|
|
│ └── skill.toml # Runtime + input schema
|
|
└── custom-skill-python/
|
|
├── SKILL.md # Overview (prompt body unused)
|
|
├── skill.toml # Runtime = python, entry = main.py
|
|
└── main.py
|
|
```
|
|
|
|
### `SKILL.md` (required)
|
|
|
|
The source of truth for the skill's prompt and identity. Must start with YAML
|
|
frontmatter containing at least `name` and `description`:
|
|
|
|
```markdown
|
|
---
|
|
name: docker
|
|
description: Docker expert for containers, Compose, and Dockerfiles.
|
|
---
|
|
|
|
You are a Docker specialist. You help users build, run, debug, and optimize
|
|
containers...
|
|
```
|
|
|
|
This format is compatible with Claude Code skills, so a `SKILL.md` authored
|
|
here can be dropped into other tools without modification.
|
|
|
|
### `skill.toml` (optional)
|
|
|
|
Add one only when you need to declare any of:
|
|
|
|
- `[runtime]` — `promptonly` / `python` / `node` / `shell` (default is `promptonly`)
|
|
- `[input]` — typed input parameter schema
|
|
- `version`, `author`, `tags` — structured metadata
|
|
|
|
```toml
|
|
[skill]
|
|
name = "meeting-agenda"
|
|
version = "0.1.0"
|
|
description = "Generate a structured meeting agenda from a topic and duration."
|
|
tags = ["meeting", "productivity"]
|
|
|
|
[runtime]
|
|
type = "promptonly"
|
|
|
|
[input]
|
|
topic = { type = "string", description = "The meeting topic", required = true }
|
|
duration_minutes = { type = "string", description = "Duration in minutes", required = true }
|
|
```
|
|
|
|
**Consistency rule:** if both files exist, `skill.name` and `skill.description`
|
|
in `skill.toml` must match the `name` and `description` in `SKILL.md`'s
|
|
frontmatter. The validator enforces this to prevent drift.
|
|
|
|
**Do not duplicate the prompt body in TOML.** The prompt lives in `SKILL.md`;
|
|
`skill.toml` is for metadata the prompt cannot express.
|
|
|
|
## Testing Skills Locally
|
|
|
|
```bash
|
|
librefang skill test ./skills/custom-skill-prompt \
|
|
--input '{"topic": "Q1 planning", "duration_minutes": "30"}'
|
|
```
|
|
|
|
## Adding a New Skill
|
|
|
|
1. Create `skills/<name>/SKILL.md` with frontmatter (`name`, `description`) and the prompt body.
|
|
2. If you need `[runtime]`, `[input]`, or structured metadata, add `skills/<name>/skill.toml`.
|
|
3. Add implementation files (`main.py`, etc.) when `runtime` is not `promptonly`.
|
|
4. Run `python scripts/validate.py`.
|
|
5. Submit a PR.
|
|
|
|
See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full guide.
|