Skills API — Get Started

Skills extend the agent with specialized expertise + bundled resources. This page walks through building an api-auditor skill end-to-end.

1. Create the directory

mkdir -p .codebuddy/skills/api-auditor/scripts

2. Write the definition

.codebuddy/skills/api-auditor/SKILL.md tells the agent WHEN to reach for the skill and HOW to behave once active:

---
name: api-auditor
description:
  Expertise in auditing and testing API endpoints. Use when the user asks to
  "check", "test", or "audit" a URL or API.
---

# API Auditor

You act as a QA engineer specialized in API reliability. When this skill is
active you MUST:

1. **Audit** — use `scripts/audit.js` to check the URL.
2. **Report** — explain status codes + latency in plain English.
3. **Secure** — warn if the user is testing a sensitive endpoint over `http:`.

3. Add the tool logic

.codebuddy/skills/api-auditor/scripts/audit.js is the code the agent runs:

const url = process.argv[2];

if (!url) {
  console.error("Usage: node audit.js <url>");
  process.exit(1);
}

console.log(`Auditing ${url}...`);
fetch(url, { method: "HEAD" })
  .then((r) => console.log(`Result: Success (Status ${r.status})`))
  .catch((e) => console.error(`Result: Failed (${e.message})`));

4. Verify discovery

CodeBuddy auto-discovers skills in .codebuddy/skills/. Check yours is found:

/skills list

You should see api-auditor.

5. Try it

Start a chat:

Can you audit http://localhost:3000

The agent matches the request against the skill description, activates the skill (with user approval), and runs:

node .codebuddy/skills/api-auditor/scripts/audit.js http://localhost:3000

The result comes back in the chat.

SKILL.md reference

YAML frontmatter for metadata, Markdown for instructions.

Field	Required	Meaning
`name`	Yes	Unique identifier
`description`	Yes	When to activate — matched against user requests
`version`	No	Semver (`1.0.0`)

Directory shape

.codebuddy/skills/
  my-skill/
    SKILL.md          # Required: definition
    scripts/          # Optional: bundled scripts
    install.sh        # Optional: install script
    requirements.txt  # Optional: Python deps

Skills catalog — the built-in skills that ship with CodeBuddy
MCP — for external tool servers instead of bundled scripts