list_skills
List all registered skills with their names, descriptions, and origins without loading body content.
The list_skills tool returns a list of all registered skills with their metadata — name, description, origin, and source path. Unlike load_skill, it does not return skill body content, making it a cheap way to discover what skills are available before deciding which one to load.
import { createAgent } from "@comma-agents/core";
const agent = createAgent({
name: "coder",
model: "openai/gpt-4o",
tools: ["list_skills", "load_skill", "read_file", "edit_file"],
});The tool is included in agent tool sets by name like any other built-in. It only succeeds when the strategy loader has wired a SkillRegistry into the agent — otherwise every call returns skill_unavailable.
Parameters
This tool takes no parameters.
Returns
On success the tool returns a human-readable list plus a structured payload:
Prop
Type
Each ListSkillsEntry contains:
Prop
Type
The text output is a compact listing of all skills:
2 skill(s) registered:
- react-practices (global): React component and hook conventions...
- ts-patterns (project): TypeScript conventions for new modules...Errors
| Error kind | Recoverable | When |
|---|---|---|
skill_unavailable | No | No skill registry is wired into this agent. The agent should stop attempting to use skills for the rest of the turn. |
See error kinds for the full taxonomy.
When to use list_skills vs load_skill
- Use
list_skillsto discover what skills exist and read their one-line descriptions. It has no context cost — only metadata is returned. - Use
load_skillwhen you've identified the skill you need and want to pull its full instructions into context.
A typical flow: call list_skills first to see what's available, then load_skill for the specific skill that matches your task.
Related
- Skills concept — how skills are authored and discovered.
load_skill— load the full body of a specific skill.- Tools overview — other tools available to agents.