Author Fullsend Augmentations

Author fullsend augmentations

Help users write skills (and sub-agents) that augment default fullsend agent behavior without fighting it. An augmentation adds domain knowledge, tightens constraints, or reformats output — it does not replace the default skill's procedure unless the user explicitly chooses override.

When to use

• The user wants to create a new skill for their repo to augment an existing agent or skill shipped by fullsend.
• The user has a skill that is being ignored or overshadowed by a default skill.
• The user wants to understand what a default skill or sub-agent already covers before writing their own.
• The user wants to add or extend a sub-agent under an orchestrator skill (for example review).
• The user is deciding whether to augment or fully override a default skill.

Hard rule: discover, do not memorize

Shipped agents, skills, harnesses, schemas, and sub-agent rosters change. Do not rely on remembered names or static tables in this skill.

Hard rule: ask where it ships before writing files

Discovery uses AGENTS_ROOT / FULLSEND_ROOT (or shallow clones) only to read harnesses, schemas, and shipped skills.

Never create or edit augmentation skills under:

• The discovery checkout (AGENTS_ROOT, FULLSEND_ROOT)
• A neutral test or discovery directory unless the user explicitly says that directory is the shipping target
• The current working directory by default

Before mkdir, write, or "create the skill", ask with concrete choices (numbered options the user can pick, plus a type-your-own path) — not a blank open question and not a stop with no options:

1. What artifact? (see Hard rule: classify artifact below — sub-agent vs augmentation skill vs org fork)
2. Which repo gets it? (app repo, org skills repo, .fullsend config repo, or upstream contribution)
3. Which placement? (see step 6 — repo .agents/skills/ vs org harness URL vs sub-agents/ under an orchestrator)

Until the user names the target path, output the draft in chat only (or write to a path the user gives you — their org skills repo, app repo, or .fullsend config repo).

Hard rule: classify artifact before writing

Sub-agents and augmentation skills are different file shapes. Classify from the user's words before creating directories. State your choice in one line (for example: "Artifact: sub-agent under pr-review").

Anti-pattern: User asked for a sub-agent → you created wrapper-name/SKILL.md (or any */SKILL.md) with the dimension embedded inside. That is wrong. Sub-agent content belongs in sub-agents/<name>.md beside siblings like correctness.md, matching their frontmatter and Own / Do not own sections.

Anti-pattern: User asked for a sub-agent on a fixed roster → you only added sub-agents/new.md without editing the parent SKILL.md roster, keyword table, and dispatch steps. That file will never run.

If ambiguous ("add a new dimension to review"), ask with concrete choices: new sub-agent vs separate augmentation skill — short descriptions and a type-your-own option.

Always fetch current facts from:

Prefer a local clone when available; otherwise use gh api / raw GitHub URLs against main (or the pin the user's org already uses).

Do not confuse fullsend's repo-root skills/ / .claude/skills/ (local Cursor/Claude tooling) with agent sandbox skills under agents → skills/.

How composition works

Multiple skills can load in one session. On overlapping topics, the model follows the more specific language. Vague augmentation ("be concise") loses to hard defaults every time.

Skill loading and name collisions

Read the current wording in fullsend:

docs/guides/user/customizing-with-skills.md

Same name as a built-in: If your repo skill directory matches a built-in skill name (for example retro-analysis), the agent never loads your version — the built-in wins and Fullsend logs a warning. Use a unique directory name (for example my-org-retro, not retro-analysis) to extend the agent, or use base: harness composition for an intentional override.

Different name: Your skill loads next to built-ins. To change behavior, be more specific than the default — exact fields, word limits, templates. Do not rely on soft guidance like "prefer concise."

Also read the agent definition — it often owns output fields more tightly than any skill.

Procedure

0. Find or clone the source repos

Before discovery, point at local clones of fullsend-ai/agents and fullsend-ai/fullsend. If they are not on disk, shallow-clone them to a temp path. Everything below reads from those trees — not from memory.

# Agents repo (runtime source of truth)
AGENTS_ROOT="${AGENTS_ROOT:-}"   # set if already cloned
if [[ -z "$AGENTS_ROOT" ]]; then
  # try common local paths, else clone shallow
  for d in "$HOME/development/agents" ./agents; do
    [[ -d "$d/harness" && -d "$d/agents" && -d "$d/schemas" ]] && AGENTS_ROOT="$d" && break
  done
fi
if [[ -z "$AGENTS_ROOT" ]]; then
  git clone --depth 1 https://github.com/fullsend-ai/agents.git /tmp/fullsend-agents
  AGENTS_ROOT=/tmp/fullsend-agents
fi

# Fullsend repo (docs + scaffold)
FULLSEND_ROOT="${FULLSEND_ROOT:-}"
if [[ -z "$FULLSEND_ROOT" ]]; then
  for d in "$HOME/development/fullsend" ./fullsend; do
    [[ -d "$d/docs/guides/user" ]] && FULLSEND_ROOT="$d" && break
  done
fi
if [[ -z "$FULLSEND_ROOT" ]]; then
  git clone --depth 1 https://github.com/fullsend-ai/fullsend.git /tmp/fullsend-core
  FULLSEND_ROOT=/tmp/fullsend-core
fi

1. Discover the target agent and what it already loads

Ask which agent(s) the user wants to affect. Then list — do not assume.

cd "$AGENTS_ROOT"

# Agents that have harnesses today
ls harness/*.yaml

# Skills each harness loads (authoritative for that checkout)
rg -n '^skills:' -A 20 harness/<agent>.yaml

# Agent system prompt / field contracts
sed -n '1,120p' agents/<agent>.md

# Output schema = required/optional JSON fields
cat schemas/<agent>-result.schema.json

# What the post-script posts to humans (comment vs issues vs review body)
rg -n 'jq -r|SUMMARY|COMMENT|body|findings|gh api|gh pr' scripts/post-<agent>.sh

Also skim fullsend user docs for extension points (names that unlock behavior when present even if not in the harness skills: list):

cd "$FULLSEND_ROOT"
rg -n 'extension point|skills/|\.agents/skills' docs/guides/user/customizing-with-skills.md docs/agents/<agent>.md

For each overlapping skill you find, open its SKILL.md and note:

• Fields or outputs it owns
• Procedures / steps it defines
• Hard rules vs soft guidance
• Whether it orchestrates sub-agents (next step)

1b. Discover sub-agents (when relevant)

Some skills are orchestrators. They dispatch specialized sub-agents whose definitions live beside the skill.

cd "$AGENTS_ROOT"

# Find every shipped sub-agent tree
find skills -type d -name sub-agents

# List roster for a skill (example pattern — use whatever find returns)
ls skills/<orchestrator-skill>/sub-agents/

# How the parent selects/dispatches them
rg -n 'sub-agent|sub_agents|roster|Dispatch' skills/<orchestrator-skill>/SKILL.md

# Read a sub-agent's ownership contract (frontmatter + Own/Do not own)
sed -n '1,80p' skills/<orchestrator-skill>/sub-agents/<name>.md

Before inventing a new sub-agent:

1. Confirm the parent skill's dispatch model:
   • Fixed roster / named selection → dropping a new file alone is not enough; the parent SKILL.md must list and dispatch the new name. See Fixed-roster orchestrators below — do not suggest legacy overlay directories.
   • Directory discovery → a uniquely named file may be enough; verify in the parent SKILL.md.
2. Check for an existing sub-agent that already owns the dimension (read Own / Do not own sections). Prefer augmenting that sub-agent's instructions over cloning a parallel one.
3. Match shipped frontmatter conventions (name, description, model, tools, permissionMode, etc.) by copying structure from a sibling file — still read a current sibling; do not invent fields from memory.

Fixed-roster orchestrators (for example pr-review)

If discovery shows a fixed roster (parent SKILL.md names sub-agents explicitly), a lone sub-agents/<name>.md is never enough by itself — the parent must learn the name or the platform must support merging that file into the upstream skill tree.

Do not hardcode today's shipping options. After reading the parent orchestrator, discover what fullsend currently supports for intra-skill / sub-agent customization:

cd "$FULLSEND_ROOT"
# User-facing guidance (preferred path lives here when features ship)
rg -n 'file-level|sub-agent|override|skills:' \
  docs/guides/user/customizing-with-skills.md \
  docs/guides/user/customizing-agents.md \
  docs/guides/user/default-vs-custom.md

# Whether harness skills: accepts object/map overrides (schema + types)
rg -n 'SkillEntry|file_overrides|Overrides' \
  docs/ ADRs/ internal/harness/ 2>/dev/null | head -40

Present shipping choices from what discovery found, not from memory. Typical families (names and availability change — verify each run):

Prefer the lightest mechanism discovery shows as supported and documented. When file-level overrides exist in the checkout you are reading, prefer them over whole-skill forks for single-file / few-file changes.

Harness skills: merge caveat (verify in Harness Field Reference): base: composition merges skill entries with deduplication by basename — a child entry whose directory name matches a base skill replaces it (child wins), not loads alongside. Say that plainly when recommending a fork.

Do not recommend customized/ or .fullsend/customized/ overlay paths.

When the user wants a new sub-agent but has not named the dimension: after the roster summary, ask with concrete choices (Performance, Observability, … plus type-your-own), derived from Own/Do-not-own gaps — not a blank "what do you want?"

1c. Map human-facing surfaces

JSON length ≠ human noise. Derive surfaces from schema + post-script, not from guesses:

Compress only the human-facing field you intend to change. Leaving detail fields intact (for example retro proposal bodies) is often correct.

2. Classify the change

For derived harnesses and agent registration, read only these fullsend entry points (skip "layered configuration" / "overriding built-in skills" sections in older user guides — they describe removed overlay mechanics):

• docs/guides/user/default-vs-custom.md — augment vs derived
• docs/ADRs/0045-forge-portable-harness-schema.md — base: merge rules
• docs/ADRs/0058-agent-registration.md — registering harness URLs
• docs/guides/user/building-custom-agents.md — new or derived agents

Use docs/guides/user/customizing-with-skills.md for repo skill layout, built-in skill names, and whatever override mechanisms that guide currently documents (re-read it every run — it changes when features ship).

2b. Lock artifact type (mandatory — do before step 4)

From the user's request and step 2, pick exactly one primary artifact:

sub-agent.md  |  augmentation SKILL.md  |  org-fork orchestrator tree

Confirm aloud:

• Sub-agent: parent orchestrator name (for example pr-review), sub-agent filename (for example performance.md), fixed roster? (yes → path A or B from 1b)
• Augmentation skill: unique skill directory name (not a built-in name)
• Org fork: which orchestrator directory is copied wholesale

If the user said sub-agent, step 4 follows the Sub-agent branch only. Do not open the Skills branch unless they change the request.