Skills

Skills are markdown guidance — how to approach a class of problem — fetched when the agent decides it needs them, and deleted after use.

Guidance, not code

A skill adds no executable capability. It is a document that tells the model how to think about a kind of task; the tools it uses to act are Coderrr's own, already gated by mode and workspace containment.

That split is the whole safety argument: the worst a malicious skill can do is give bad advice to an agent whose tools are already constrained.

This changed in v2

v1 skills shipped Python tools that the CLI downloaded and executed — remote, unreviewed code running outside any sandbox. v2 fetches only the markdown. Registry documents that still say "run python tools/<name>.py" refer to scripts v2 will not provide, and need rewriting against Coderrr's tool set.

Retrieval is automatic

You do not install skills. While analysing your request during planning, the agent consults the registry index, decides whether anything there is relevant, and loads only what it needs. Skills that were loaded are dropped from disk when the session ends.

Coderrr needs the network for inference anyway, so re-fetching costs a round trip and nothing else — and it guarantees the agent always runs against current guidance rather than a stale local copy.

Tool	When the agent uses it
search_skills	While working out what the request involves
load_skill	When a search hit looks relevant enough to read

Browsing the registry yourself

coderrr skills search "pdf report"

  Skill          Description
  pdf-generator  Create and edit PDF documents, extract text and tables...
  data-analysis  Load, clean, and summarise tabular data with pandas...

This is a read-only lookup — it tells you what guidance exists, it does not install anything.

The default registry

Skills come from Akash-nath29/coderrr-skills. A single registry.json indexes each skill, and each skill directory holds a Skills.md with the guidance.

{
  "version": "1.0",
  "skills": {
    "web-scraper": {
      "name": "web-scraper",
      "displayName": "Web Scraper",
      "description": "Fetch, parse, and extract content from web pages...",
      "version": "1.0.0",
      "author": "Akash Nath",
      "download_url": ".../main/skills/web-scraper",
      "tags": ["web", "scraping", "http"]
    }
  }
}

The description field is what search matches against, so it should describe when to reach for the skill, not just what it is about.

Using your own registry

Point [skills].registry at any URL serving the same shape — a team registry of internal conventions, or your own fork:

[skills]
registry  = "https://internal.example.com/coderrr/registry.json"
ephemeral = true

Key	Default	What it does
registry	coderrr-skills	URL of a registry.json index
ephemeral	true	Delete fetched skills from disk after use. Leave this on.

Limits on what gets fetched

Constraint	Value
Entry file	`Skills.md` only — `tools/` is never fetched
Maximum size	256 KB. Guidance is prose; anything larger is not a skill.
Frontmatter	Stripped before the body enters context — the registry already supplies name and description
Lifetime	Deleted when the session ends

Writing a skill

A skill is a Skills.md with YAML frontmatter and a body of guidance. Write the body for a model that already has read, write, sandbox, and spec tools — describe the approach, the pitfalls, and how to verify, not the mechanics of editing files.

---
name: pdf-generator
description: Create and edit PDF documents, extract text and tables. Use when
  the request involves reading, generating, or filling PDFs.
---

## When this applies

...

## Approach

1. ...

## Verifying

...

Contribute one to the coderrr-skills repository, or keep it in a registry of your own. See Configuration for the registry setting.