Skills

A skill is a Markdown file that gives Geoff Code specialized knowledge — a coding standard, a deployment runbook, a review checklist. The agent reads a skill’s description up front and pulls in the full content only when a task calls for it, so skills extend what the agent knows without bloating every prompt. Skills are knowledge; plugins are packages and MCP servers are executable tools. Use a skill to define a code style or workflow; use a plugin or MCP server to add a runnable capability.

SKILL.md format

A skill is a directory with a SKILL.md file. The file is YAML frontmatter followed by Markdown:

---
name: python-standards
description: Python style, tooling, and review rules for this team.
---

## Tooling
Use `uv` for envs, `ruff` for lint/format, `pyright` for types, `pytest` for tests.

## Style
- Full type annotations on public functions.
- Prefer dataclasses over dicts for structured data.
- Conventional Commits for messages.

Frontmatter

Field	Required	Description
`name`	yes	1–64 chars, lowercase letters, numbers, and hyphens only.
`description`	recommended	1–1024 chars, shown during skill discovery so the agent knows when to use it.
`license`, `metadata`	no	Additional attributes.

If description is omitted, Geoff Code falls back to the first non-empty body line (truncated), then to a default.

Directory layout

A skill directory can carry supporting files alongside SKILL.md:

my-skill/
├── SKILL.md        # required
├── scripts/        # optional helper scripts
├── references/     # optional reference docs
└── assets/         # optional assets

A single .md file placed directly in a skills directory also works as a flat skill — the filename becomes the skill name.

Where skills are discovered

Geoff Code scans these locations, in priority order (Project beats User beats Extra):

Scope	Directories
Project	`.geoff/skills/`, `.agents/skills/` (relative to the repo root)
User	`~/.geoff/skills/`, `~/.agents/skills/`
Extra	Directories from `extra_skill_dirs` in config, or the `--skills-dir` flag
Built-in	Skills shipped with Geoff Code

On a name collision, the higher-priority scope wins.

Adding extra directories

Append directories without replacing the auto-discovered ones, either per run:

geoff --skills-dir ~/team-skills --skills-dir ./repo-skills

…or persistently in ~/.geoff/config.toml:

extra_skill_dirs = ["~/team-skills"]

To merge every available skill directory rather than resolving by priority, set merge_all_available_skills = true in config.

Activating skills

Skills are presented to the agent grouped by scope so it can pick context-appropriately. There are two ways in:

Manual — invoke a skill explicitly with /skill:<name>, optionally followed by extra instructions.
Automatic — the agent activates a skill on its own when a task matches its description.

Built-in skills

Geoff Code ships built-in skills, including mcp-config (configure MCP servers and handle MCP OAuth login) and update-config (edit your Geoff Code configuration). Invoke them like any other skill, for example /skill:mcp-config.

Plugins

Package skills for distribution and versioning.

Agents

Hand skill-driven work to specialized subagents.

Getting Started

Extending

Reference

SKILL.md format

Frontmatter

Directory layout

Where skills are discovered

Adding extra directories

Activating skills

Built-in skills

Plugins

Agents

​SKILL.md format

​Frontmatter

​Directory layout

​Where skills are discovered

​Adding extra directories

​Activating skills

​Built-in skills

​Related

Plugins

Agents

SKILL.md format

Frontmatter

Directory layout

Where skills are discovered

Adding extra directories

Activating skills

Built-in skills

Related