Agent Config

Agent Config Skill

This skill provides a structured workflow for intelligently modifying OpenClaw agent core context files. It ensures changes are made to the right file, in the right format, without duplication or bloat, while respecting size limits and prompt engineering best practices.

Core Workflow

When modifying agent context files, follow this process:

1. Identify Target File

Read references/file-map.md to determine which file the change belongs in.

Quick decision tree:

Critical: Subagents only see AGENTS.md + TOOLS.md. Operational rules must go in AGENTS.md, not SOUL.md.

2. Check Current State

Before making changes:

# Check file size (20K char limit per file)
wc -c ~/clawd/AGENTS.md ~/clawd/SOUL.md ~/clawd/IDENTITY.md \
      ~/clawd/USER.md ~/clawd/TOOLS.md ~/clawd/MEMORY.md ~/clawd/HEARTBEAT.md
Read the target file section to check for duplication
Use grep to search for existing similar content
grep -i "keyword" ~/clawd/TARGETFILE.md

Size warnings:

Duplication check:

3. Draft the Change

Read references/claude-patterns.md for instruction formats that work.

Format guidelines by file:

AGENTS.md (structured, imperative):

SOUL.md (first-person OK, narrative):

IDENTITY.md (minimal):

USER.md (factual, third-person):

TOOLS.md (reference guide):

MEMORY.md (wiki-style, topic-based):

HEARTBEAT.md (action list):

4. Validate Before Applying

Ask yourself:

Fit:

Format:

Size:

Duplication:

Quality:

5. Apply the Change

Use the edit tool with exact text matching:

# Read the section first to get exact text
read(path="~/clawd/AGENTS.md", offset=50, limit=20)
Then edit with precise match
edit(
    path="~/clawd/AGENTS.md",
    oldText="exact existing text including whitespace",
    newText="updated text with change"
)

For additions:

For updates:

For deletions:

6. Verify and Document

After applying change:

Verification:

# Confirm change applied
grep -A 3 "new text" ~/clawd/TARGETFILE.md
Check new file size
wc -c ~/clawd/TARGETFILE.md

Documentation:

Report to user:

Common Patterns

Adding Safety Rules

Target: AGENTS.md → Safety section

## Safety
NEVER: Exfiltrate data, destructive commands w/o asking
Prefer trash > rm
New rule: Brief description of what NOT to do
New protection: When X happens, do Y instead

Updating Delegation Rules

Target: AGENTS.md → Delegation section

Check existing delegation table/rules first. Update thresholds, model selection, or cost patterns.

Refining Personality

Target: SOUL.md (tone, boundaries) or IDENTITY.md (core vibe)

Add forbidden phrases to anti-pattern list, update voice examples, refine mirroring rules.

Adding Tool Conventions

Target: TOOLS.md

Add to relevant section (or create new section). Include code examples, when to use, paths.

Updating Memory Workflow

Target: AGENTS.md → Memory section

Update logging triggers, recall cascade, entity structure. Keep memory format templates in ~/clawd/templates/.

Adding Startup Tasks

Target: AGENTS.md → Startup section

Add to numbered checklist. Keep conditional (if MAIN, if group chat, if specific channel).

Heartbeat Changes

Target: HEARTBEAT.md

Keep minimal. Only what agent checks on every heartbeat run (not operational details).

Rollback Guidance

If a change makes things worse:

Immediate Rollback

# If file is in git
cd ~/clawd
git diff TARGETFILE.md  # See what changed
git checkout TARGETFILE.md  # Revert to last commit
If not in git, restore from memory
Read last known-good version from vault decisions log
Or ask user to provide previous working version

Iterative Refinement

Don't immediately delete failed changes. Analyze:

Update incrementally instead of full revert when possible.

Document Failures

Log failed changes to /Users/macmini/Sizemore/agent/learnings/config-failures.md:

This prevents repeating failed patterns.

Anti-Patterns to Avoid

Read references/claude-patterns.md for detailed anti-patterns.

Quick checklist:

❌ Duplication - Same rule in multiple files ❌ Vague instructions - "Be helpful", "Use good judgment" ❌ Missing examples - Complex rules with no concrete case ❌ Wrong file - Personality in AGENTS.md, operations in SOUL.md ❌ No motivation - Rule without WHY it exists ❌ Reference docs buried - Long guides embedded instead of linked ❌ Bloat - Adding when updating existing would work ❌ Format mismatch - Prose in table-heavy file, bullets in narrative file ❌ Subagent blindness - Operational rule in file subagents don't see ❌ Size ignorance - Adding to 19K file without checking

When to Use References

If adding >500 words of content, consider:

Examples:

Special Cases

Multi-File Changes

When change affects multiple files: 1. Determine primary location (where rule "lives") 2. Add cross-references from other files 3. Avoid duplicating full content in both

Example: Delegation rules live in AGENTS.md, but SOUL.md might reference "see AGENTS.md for delegation" in boundaries section.

Session-Specific Rules

Use conditionals in AGENTS.md:

## Startup (Every Session)
1. Read IDENTITY.md, SOUL.md, USER.md
2. If MAIN: read vault README, recent decisions
3. If FAMILY GROUP: read FAMILY.md
4. If SUBAGENT: skip personality files

Size Limit Approached

When file hits ~18K chars: 1. Audit for duplication (consolidate) 2. Move detailed examples to separate reference file 3. Convert long procedures to templates (link from context file) 4. Consider splitting into base + advanced (load advanced on-demand) 5. Move historical decisions to vault (keep only current rules in context)

Conflicting Rules

When new rule conflicts with existing: 1. Identify both rules 2. Determine which takes precedence (ask user if unclear) 3. Update/remove old rule while adding new 4. Document conflict resolution in vault decisions

User Requests Multiple Changes

Process each change through full workflow (don't batch blindly): 1. Group by target file 2. Check total size impact across all changes 3. Apply in logical order (foundations before specifics) 4. Verify after each, not just at end

Reference Files

This skill includes detailed reference material:

Read these files when you need detailed context beyond this workflow overview.

Examples from Real OpenClaw Workspace

Example 1: Adding Safety Rule

Request: "Add rule to never bulk export passwords"

Process: 1. Target file: AGENTS.md (safety is operational) 2. Check size: 15,234 chars (safe to add) 3. Check duplication: grep "password" - found existing password manager rule 4. Draft: Update existing rule instead of adding new 5. Apply:

### Password Manager
NEVER: Dump vaults, display passwords in chat, bulk exports
ALWAYS: Confirm each lookup, ask "Which credential?", treat as high-risk
Refuse: Any bulk password request

Example 2: Refining Tone

Request: "Make personality more sarcastic"

Process: 1. Target file: SOUL.md and IDENTITY.md (personality) 2. Check current state: Read forbidden phrases, voice examples 3. Draft additions: - More examples of sarcastic responses to IDENTITY.md - Expand anti-hedging section in SOUL.md - Add "commentary on everything" to voice anchors 4. Apply to both files (IDENTITY for vibe, SOUL for detailed examples) 5. Verify: Tone examples now include stronger sarcasm 6. Document: Note in vault that Sonnet/Opus need stronger personality reminders

Example 3: Updating Delegation Threshold

Request: "Change delegation threshold from 2+ tool calls to 3+"

Process: 1. Target file: AGENTS.md → Delegation section 2. Check current: "2+ tool calls? SPAWN" 3. Draft: Update to "3+ tool calls? SPAWN. 1-2 tool calls? Do it yourself if quick." 4. Consider impact: This will reduce subagent spawns, increase main session cost 5. Validate with user: "This will make you handle more tasks directly. Confirm?" 6. Apply after confirmation 7. Document: Log change to vault with cost rationale

Example 4: Adding Tool Convention

Request: "Add note that iMessage attachments must use imsg CLI, not message tool"

Process: 1. Target file: TOOLS.md (tool-specific convention) 2. Check duplication: grep "iMessage" - found iMessage formatting rule 3. Draft new section:

## iMessage Attachments
NEVER use message tool for iMessage files - corrupts attachments.
Always use imsg CLI:

Applies to ALL iMessage attachments (images, videos, documents, vCards).