Configuring Agents with Skills

Fullsend agents use agent skills — self-contained markdown documents that teach an agent how to perform a specific task. Each default agent ships with built-in skills, and you can extend or replace them by committing your own skills to your repository.

For general project-wide instructions (code style, test conventions, architecture rules), see Configuring with AGENTS.md. This guide covers skills specifically.

What is a skill?

A skill is a directory containing a SKILL.md file with YAML frontmatter and structured instructions. The agent loads the skill by name and follows its instructions during execution.

.agents/skills/my-skill/
  SKILL.md           # skill definition (required)
  scripts/           # supporting scripts (optional)
    helper-script.sh
  references/        # reference data (optional)
    data.json

For portability across agent runtimes, store skills in .agents/skills/ and symlink .claude/skills to it:

ln -s ../.agents/skills .claude/skills

This way, skills are discoverable by fullsend's agent runtime and by any local agent tooling developers use when working on the repo directly.

The SKILL.md has frontmatter declaring the skill's name and description, followed by step-by-step instructions:

---
name: my-skill
description: >-
  One-line summary of what this skill does.
---

# My Skill

Instructions the agent follows when this skill is invoked.

## Step 1: Gather context

...

## Step 2: Produce output

...

Skills can reference companion scripts and data files in the same directory, giving agents the ability to dynamically gather information at runtime.

Adding skills to your repository

Place skills in .agents/skills/ in your target repository and symlink .claude/skills to .agents/skills. All agents operating on your repo will discover them automatically:

your-repo/
  .agents/skills/
    customer-research/
      SKILL.md
      scripts/
        query-salesforce.sh
    deployment-checks/
      SKILL.md
  .claude/skills -> ../.agents/skills

Extending agents with repo skills

Skills you add to your repository are available to all fullsend agents alongside the built-in skills. This is the primary way to give agents domain-specific capabilities — linting rules, deployment checklists, architecture constraints — without modifying any fullsend configuration.

Repo skills extend the agent's skill set. They do not replace built-in skills. If a repo skill has the same name as a built-in skill, the built-in version takes precedence and the repo version is silently ignored. Use a unique name to ensure your skill is discoverable.

Skill precedence

Fullsend uploads built-in skills to the agent's personal-level config directory (CLAUDE_CONFIG_DIR/skills/). Repo skills live in the project-level .claude/skills/ directory. Claude Code resolves name collisions using precedence:

Personal (CLAUDE_CONFIG_DIR/skills/)  >  Project (.claude/skills/)
         fullsend built-in skills            repo skills

A repo skill with a novel name (no collision) is always available. A repo skill with a name matching a built-in skill is shadowed — the agent never sees it.

Extension points

Some agents recognize skill names that do not ship with fullsend. Providing these unlocks additional capabilities. See each agent's documentation for the skills it supports — for example, the prioritize agent uses a customer-research skill when available.

Overriding built-in skills

To intentionally replace a built-in skill with your own version, use base: composition and config-driven agent registration. Register the agent in config.yaml with a harness that uses base: to inherit from the upstream harness, and include your replacement skill in the skills: list. The directory name must match the built-in skill name exactly.

See Bring Your Own Agent for the full composition model and config-driven registration.

Built-in skills

These skills ship with fullsend and can be overridden via config-driven agent registration:

Agent	Skill	Purpose
Triage	issue-labels	Label discovery and application during triage
Code	code-implementation	Step-by-step implementation procedure
Review	code-review, pr-review, docs-review, issue-labels	Review evaluation across dimensions
Fix	fix-review	Review feedback interpretation and fix strategy
Prioritize	customer-research	Customer data gathering for RICE scoring (extension point)
Retro	retro-analysis, finding-agent-runs	Workflow analysis and proposal generation

When to use skills vs. AGENTS.md

Use skills when you need to change how a specific agent performs a specific task — especially when the configuration involves domain knowledge, helper scripts, or external data sources that only one agent needs.

Use AGENTS.md for broad instructions that apply to all agents and human contributors alike.

Authoring skills that augment defaults

Adding a skill is easy; writing one that works beside shipped defaults is harder. Defaults often use specific language and own concrete output fields. A soft "prefer concise" skill will lose that contest.

When you are tuning a built-in agent (triage, retro, review, …):

1. Discover what the agent already loads (harness skills:, agent markdown, result schema, post-script human surfaces).
2. Choose the right artifact: unique-named augmentation skill, sub-agent under an orchestrator, or whole-skill override — not a same-named drop-in that gets shadowed.
3. Prefer hard limits and field ownership over soft preferences.
4. Re-check current docs for the lightest shipping path (repo skill, harness pin, file-level override when available, or upstream contribution).

For the full procedure, use the contributor skill author-fullsend-augmentations (local checkout of this repo, or any environment that loads skills/author-fullsend-augmentations/).

Bring Your Own Agent covers the same decision frame in Tuning agents with augmentation skills.

Planned: Per-file overrides inside skill directories (#6158) will make single sub-agent customization lighter than forking a whole skill tree.

What not to do

• Don't duplicate AGENTS.md content in skills. If an instruction applies to all agents, put it in AGENTS.md. Skills are for agent-specific behavior.
• Don't reuse a built-in skill directory name unless you intend a supported whole-skill override path — same-named project skills are shadowed by built-ins (see Skill precedence).

See also

• Customizing Agents — overview of all customization approaches
• Bring Your Own Agent — building, registering, and tuning existing agents
• author-fullsend-augmentations — discovery-driven authoring procedure for augmentations and sub-agents
• Default, derived, and custom agents — adding skills keeps you in "configured default agent" territory