librefang-registry/skills

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:

---
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

[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

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 for the full guide.