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".
In this repository44 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- analyze-dataSkill
- brainstormingSkill
- craft-lessonSkill
- create-agentSkill
- create-skillSkill
- customize-skillSkill
- designSkill
- deslopSkill
- developSkill
- discovery-reportSkill
- elicitationSkill
- empathy-mapSkill
- explore-ideaSkill
- grill-meSkill
- help-meSkill
- humanizeSkill
- incidentSkill
- iterateSkill
- journey-mapSkill
- jtbdSkill
- kanbanSkill
- launchSkill
- legal-safety-auditSkill
- maintenance-executeSkill
- maintenance-planSkill
- memorySkill
- motionSkill
- phaseSkill
- planSkill
- research-planSkill
- retroSkill
- reviewSkill
- root-causeSkill
- round-tableSkill
- shape-upSkill
- shut-upSkill
- statusSkill
- teach-meSkill
- testSkill
- unpack-problemSkill
- validate-ideaSkill
- validation-patternsSkill
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
- Distinctive: line 26
When you just want to document a project context/convention (use memory instead)
- Very specific: line 27
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)
- Very specific: line 28
When the change is about a skill, not an agent (use /customize-skill)
- Very specific: line 34
If the agent has no customize.toml defaults yet, the merge will apply your override cleanly
- Distinctive: line 65
Ask the user or extract from context what they want to change using these probes:
- Very specific: line 91
If the user's intent doesn't map to an existing field, create a clean entry under [conventions].
- Very specific: line 110
Create or update .agents/custom/<agent>.toml.
- Distinctive: line 123
Check the JSON output:
- Distinctive: line 126
No syntax or TOML parsing errors occur
- Very specific: line 174
Overriding entire files for single-field changes: Only put altered fields in .agents/custom/<agent>.toml.
- Very specific: line 175
Forgetting to verify: Always run merge_customization.js to confirm the output is as expected.
≈ “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.
Files
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.tomldefaults 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/*.tomlwhen 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 -->sectionname,icon,originfrontmatter 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:
- Which agent? (e.g.,
@developer,@architect) - What specific behavior or setting? (e.g., temperature, model, coding rules, tool access)
- What is the current value (if known)?
- What should the new value be?
- 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:
| Intent | Field | Type |
| More/less creativity | temperature | number |
| Different model | model | string |
| Add/remove capability | capabilities | array of strings |
| Change permissions | permission | table |
| Add/configure tool access | tools | table |
| Adjust core principles | principles | array of strings |
| Project-specific conventions | conventions | table |
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>.tomlalready 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>.tomlStep 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:** activeMerge rules (for verification)
| Value type | Rule |
| 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 id | Keyed merge — matching entries replace, new entries append |
| All other arrays | Append |
Troubleshooting & Edge Cases
| Issue | Root Cause | Solution |
| Merge script output unchanged | Misspelled field key or invalid TOML table syntax | Inspect .agents/custom/<agent>.toml line by line against customize.toml default keys |
| Frontmatter error | Attempted to override name or origin | Remove identity keys from .agents/custom/<agent>.toml |
| Array overwrite instead of merge | Scalar array type override | Note that scalar arrays (strings/numbers) append by default; table arrays with code/id replace matching entries |
Anti-patterns
- Editing agent
.mdfiles directly. Your changes will be wiped on the nextnpx vespyrupgrade. - Overriding entire files for single-field changes. Only put altered fields in
.agents/custom/<agent>.toml. - Forgetting to verify. Always run
merge_customization.jsto confirm the output is as expected.
Output Artifacts
.agents/custom/<agent>.toml(the override file)artifacts/memory/active-decisions.md(audit log entry)
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
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.

