agentleFS
lalulalilalulali/vespyr/.agents/skills/customize-agent/SKILL.md

customize-agent

Skill11 starsChanged 10 days agoMITView on GitHub

Guided authoring flow for agent customization — describe your intent, map it to override fields, write the TOML, and verify it works. Use this skill whenever you need to modify, customize, adjust, or override any Vespyr agent's settings, model, temperature, capabilities, permissions, or conventions without editing the agent file directly. Trigger on "customize @developer", "change the model for @architect", "override agent settings", "adjust agent temperature", "add a capability to @qa-engineer".

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 4 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When you just want to document a project context/convention (use memory instead)

    line 26
  2. Very specific:

    When you want to change the agent's identity or role itself (create a new agent with /create-agent, or edit the agent source directly)

    line 27
  3. Very specific:

    When the change is about a skill, not an agent (use /customize-skill)

    line 28
  4. Very specific:

    If the agent has no customize.toml defaults yet, the merge will apply your override cleanly

    line 34
  5. Distinctive:

    Ask the user or extract from context what they want to change using these probes:

    line 65
  6. Very specific:

    If the user's intent doesn't map to an existing field, create a clean entry under [conventions].

    line 91
  7. Very specific:

    Create or update .agents/custom/<agent>.toml.

    line 110
  8. Distinctive:

    Check the JSON output:

    line 123
  9. Distinctive:

    No syntax or TOML parsing errors occur

    line 126
  10. Very specific:

    Overriding entire files for single-field changes: Only put altered fields in .agents/custom/<agent>.toml.

    line 174
  11. Very specific:

    Forgetting to verify: Always run merge_customization.js to confirm the output is as expected.

    line 175

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Customize Agent — Agent Override Authoring

What this skill does

Helps you customize any Vespyr agent without editing the agent file directly. You describe what you want to change, the skill maps your intent to the correct override fields, writes a .agents/custom/<agent>.toml file, and verifies the merge works.

When to use

  • "Customize @developer to use a higher temperature"
  • "Change the model for @architect"
  • "Add a new capability to @qa-engineer"
  • "Override the developer guidelines for this project"
  • "Set custom conventions for @tech-lead"

When NOT to use

  • For one-off behavior changes in a single prompt (just instruct the agent in your prompt)
  • When you just want to document a project context/convention (use memory instead)
  • When you want to change the agent's identity or role itself (create a new agent with /create-agent, or edit the agent source directly)
  • When the change is about a skill, not an agent (use /customize-skill)

Prerequisites

  • The agent file exists under .agents/agents/<name>.md
  • You know which agent you want to customize
  • If the agent has no customize.toml defaults yet, the merge will apply your override cleanly

How customization works

Override files live in .agents/custom/<name>.toml and are never touched by upgrades. A defaults file (.agents/agents/<name>/customize.toml) is optional — merge_customization.js treats a missing defaults file as empty, so an override alone is valid.

The merge script combines defaults + override and prints the merged result as JSON for verification. The override file wins on conflicts.

[!IMPORTANT] Known gap: the merged output is a validated preview only. No runtime component currently consumes .agents/custom/*.toml when an agent loads — until that wiring exists, overrides are declarations, not applied settings. Do not claim an override changed an agent's behavior.

Safety & Governance Principles

Principle of Least Surprise

Customization overrides alter agent defaults for your entire workspace. Do not create overrides that introduce unexpected side effects, break existing agent contracts, or silently alter team-wide security configurations without explicit confirmation from the user.

Non-Overridable Core Identity

The following agent frontmatter and blocks are hardcoded and cannot be overridden via TOML:

  • <!-- IDENTITY: do not edit --> section
  • name, icon, origin frontmatter fields

Everything else in customize.toml defaults (temperature, model, permissions, capabilities, principles, conventions) is fully overridable.


Workflow

Step 1: Capture Intent (Socratic Probes)

Ask the user or extract from context what they want to change using these probes:

  1. Which agent? (e.g., @developer, @architect)
  2. What specific behavior or setting? (e.g., temperature, model, coding rules, tool access)
  3. What is the current value (if known)?
  4. What should the new value be?
  5. Why this change?

Example intents:

  • "I want @developer to be more creative — set temperature to 0.5"
  • "I want @architect to always use TypeScript interfaces, not types"
  • "I want @qa-engineer to skip performance tests by default"

Step 2: Map Intent to Override Fields

Inspect .agents/agents/<name>/customize.toml (if available) or the agent's markdown definition to identify target fields:

IntentFieldType
More/less creativitytemperaturenumber
Different modelmodelstring
Add/remove capabilitycapabilitiesarray of strings
Change permissionspermissiontable
Add/configure tool accesstoolstable
Adjust core principlesprinciplesarray of strings
Project-specific conventionsconventionstable

If the user's intent doesn't map to an existing field, create a clean entry under [conventions].

Step 3: Build the Override TOML

Construct the .agents/custom/<agent>.toml content. Keep it minimal — include only the fields being changed.

# developer.toml — project-specific overrides for @developer
temperature = 0.5
model = "anthropic/claude-sonnet-4.6"

[conventions]
testing = "vitest + @testing-library/react"
exports = "named exports only, no default exports"
quotes = "single quotes, no semicolons"

Step 4: Write the Override File

Create or update .agents/custom/<agent>.toml.

[!IMPORTANT] If .agents/custom/<agent>.toml already exists, read it first, merge the new fields into existing keys surgically, and write back the updated file. Do NOT blindly overwrite existing custom settings.

Step 5: Verify the Merge

Run:

node .agents/scripts/merge_customization.js <agent-name>

Check the JSON output:

  • The overridden field reflects your new value
  • Unchanged fields show the default values
  • No syntax or TOML parsing errors occur

Report to the user:

Customization applied to @<agent>:
  temperature: 0.1 → 0.5
  model: unchanged (claude-sonnet-4.6)

Override file: .agents/custom/<agent>.toml

Step 6: Log the Change

Append to artifacts/memory/active-decisions.md:

### [DECISION] Customized @<agent> [date: YYYY-MM-DD]
**Changes:** {summary of what was changed and why}
**Override file:** .agents/custom/<agent>.toml
**Status:** active

Merge rules (for verification)

Value typeRule
Scalars (string, number, boolean)Override wins over default
Tables (nested objects)Deep merge — override keys replace, new keys add
Arrays of tables with code or idKeyed merge — matching entries replace, new entries append
All other arraysAppend

Troubleshooting & Edge Cases

IssueRoot CauseSolution
Merge script output unchangedMisspelled field key or invalid TOML table syntaxInspect .agents/custom/<agent>.toml line by line against customize.toml default keys
Frontmatter errorAttempted to override name or originRemove identity keys from .agents/custom/<agent>.toml
Array overwrite instead of mergeScalar array type overrideNote that scalar arrays (strings/numbers) append by default; table arrays with code/id replace matching entries

Anti-patterns

  • Editing agent .md files directly. Your changes will be wiped on the next npx vespyr upgrade.
  • Overriding entire files for single-field changes. Only put altered fields in .agents/custom/<agent>.toml.
  • Forgetting to verify. Always run merge_customization.js to confirm the output is as expected.

Output Artifacts

  • .agents/custom/<agent>.toml (the override file)
  • artifacts/memory/active-decisions.md (audit log entry)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.