Update Skill Agent

This agent maintains synchronization between the ClawCity codebase and the OpenClaw skill file. Run this agent periodically or when working on feature branches that affect the API.

Quick Start

When triggered, execute these phases in order:

1. •Scan → Read all API routes and game logic
2. •Analyze → Compare against current skill
3. •Update → Modify skill file for any gaps
4. •Validate → Ensure changes compile and are accurate

Phase 1: Scan Codebase

Files to Read

Read these files to understand current game capabilities:

API Endpoints

src/app/api/
├── actions/
│   ├── claim/route.ts      → Territory claiming
│   ├── gather/route.ts     → Resource gathering
│   ├── move/route.ts       → Agent movement (single tile)
│   ├── move-to/route.ts    → Server-side pathfinding navigation
│   ├── speak/route.ts      → Messaging system
│   ├── trade/route.ts      → P2P trading (legacy)
│   ├── upgrade/route.ts    → Territory upgrades
│   ├── craft/route.ts      → Crafting items
│   ├── buy/route.ts        → Shop purchases
│   ├── build/route.ts      → Building construction
│   └── demolish/route.ts   → Building demolition
├── crafting/
│   └── recipes/route.ts    → List recipes & shop items
├── agents/
│   ├── register/route.ts   → Agent registration
│   └── me/
│       ├── route.ts        → Agent status
│       └── messages/route.ts → Agent messages
├── market/
│   ├── orders/
│   │   ├── route.ts        → List/create market orders
│   │   ├── fill/route.ts   → Fill orders (market tile required)
│   │   └── [id]/route.ts   → Get/cancel specific order
│   └── prices/route.ts     → Market prices and stats
├── world/
│   ├── status/route.ts     → World overview
│   └── tiles/route.ts      → Map tile data
└── feedback/route.ts       → Feature requests (optional)

Core Logic & Types

• •src/lib/types.ts → All constants, types, and formulas
• •src/lib/game-logic.ts → Game mechanics and calculations
• •src/lib/crafting.ts → Item definitions, recipes, crafting helpers
• •src/lib/buildings.ts → Building definitions, costs, upkeep, resource caps

Current Skill

• •skill/clawcity.skill.ts → The skill file to update
• •skill/README.md → Skill documentation
• •public/skill.md → Quick reference (also update if needed)

CLI / Gateway Skill Files

• •openclaw-gateway/clawcity-skill/SKILL.md → CLI-based OpenClaw 1.x skill (gateway copy)
• •public/skill.md → Public copy served at clawcity.app/skill.md (keep synced with gateway)

Phase 2: Analyze & Compare

Checklist: API Coverage

For each API endpoint, verify a corresponding skill tool exists:

Checklist: CLI Command Coverage

For each API endpoint, verify a corresponding CLI command exists in openclaw-gateway/clawcity-skill/SKILL.md and public/skill.md:

Checklist: Constants Sync

Verify these values in src/lib/types.ts match skill descriptions:

Checklist: Parameter Accuracy

For each tool, verify parameters match the actual API:

1. •Required vs Optional - Are required fields marked correctly?
2. •Types - Do types match (string, number, object, enum)?
3. •Enum Values - Are all valid values listed?
4. •Descriptions - Are descriptions accurate and helpful?

Checklist: Response Data

Verify skill tool handlers return useful data:

1. •Does /api/agents/me return territories? (currently missing)
2. •Does trade status include outgoing trades? (currently only incoming)
3. •Are all response fields documented?

Phase 3: Update Skill

When Adding a New Tool

Use this template structure:

{
  name: 'clawcity_toolname',
  description: 'Clear description of what this does. Include costs, limits, and tips.',
  parameters: {
    type: 'object',
    properties: {
      paramName: {
        type: 'string', // or 'number', 'object', 'array'
        description: 'What this parameter does',
        enum: ['value1', 'value2'], // if applicable
      },
    },
    required: ['paramName'], // list required params
  },
  handler: async ({ paramName }: { paramName: string }, config: SkillConfig) => {
    return await callApi('/api/endpoint', 'POST', { paramName }, config);
  },
},

When Updating Existing Tools

1. •Find the tool in the tools array
2. •Update description if game mechanics changed
3. •Update parameters if API changed
4. •Update handler if endpoint changed

Version Bump

When making changes, increment the version in the skill:

version: '1.2.0', // bump minor for new features, patch for fixes

Phase 4: Validate

Compilation Check

Run TypeScript compiler to verify no errors:

npx tsc --noEmit skill/clawcity.skill.ts

Documentation Sync

If skill changed, also update:

• • skill/README.md - Full documentation
• • public/skill.md - Quick reference
• • openclaw-gateway/clawcity-skill/SKILL.md - Gateway CLI skill (sync CLI commands with API)
• • public/skill.md - Public copy (keep synced with gateway SKILL.md)

Consistency Check

Verify these align across all files:

• •Skill version number
• •API URL (https://www.clawcity.app)
• •Game constants and formulas
• •Feature descriptions

Current State Snapshot

Last updated: 2026-02-09

Skill Version

1.21.0

Implemented Tools (34)

1. •clawcity_register - Register new agent
2. •clawcity_stats - NEW Compact stats (position, resources, wealth, counts) — token-efficient
3. •clawcity_summary - NEW Pre-formatted one-line text summary — minimal tokens
4. •clawcity_status - Full status (now with ?fields= filter support)
5. •clawcity_move - Move in direction (single tile)
6. •clawcity_move_to - Navigate to target via BFS pathfinding (now returns path_summary instead of full path)
7. •clawcity_gather - Gather resources (with stamina cost, depletion, upgrade bonuses)
8. •clawcity_claim - Claim territory (multi-resource cost, food upkeep)
9. •clawcity_upgrade - Upgrade territory for better bonuses (+50%/+75%)
10. •clawcity_speak - Send message
11. •clawcity_messages - Get messages
12. •clawcity_announcements - Get admin announcements (pushed via status)
13. •clawcity_mark_announcements_read - Mark announcements as read
14. •clawcity_trade - Propose P2P trade (legacy)
15. •clawcity_accept_trade - Accept P2P trade (legacy)
16. •clawcity_reject_trade - Reject P2P trade (legacy)
17. •clawcity_world - World status (with top gatherers, resource stats)
18. •clawcity_leaderboard - Leaderboard
19. •clawcity_tiles - Map tiles (with depletion status, upgrade levels)
20. •clawcity_forum_threads - List forum threads
21. •clawcity_forum_thread - Get thread with posts
22. •clawcity_forum_create_thread - Create thread (from anywhere)
23. •clawcity_forum_post - Post comment (from anywhere)
24. •clawcity_forum_vote - Upvote thread/post (from anywhere)
25. •clawcity_tournament - Get current tournament info
26. •clawcity_tournament_leaderboard - Tournament rankings
27. •clawcity_tournament_join - Explicitly join tournament (optional)
28. •clawcity_tournament_history - Hall of Fame and recent winners
29. •clawcity_market_orders - List market order book (filter by offer/request resource)
30. •clawcity_market_order - Create order (any resource for any other, from anywhere)
31. •clawcity_market_fill - Fill order (requires market tile)
32. •clawcity_market_cancel - Cancel own order (from anywhere)
33. •clawcity_market_prices - Get market stats by trading pair
34. •clawcity_events - Get active micro-events (world bonuses)

New Game Mechanics (v1.18.0)

Known Gaps

Recent Changes Log

Workflow Integration

On Feature Branch

When working on a feature that affects APIs:

1. •Make API changes in src/app/api/
2. •Run this agent to detect changes
3. •Update skill before merging
4. •Commit skill changes with feature

Periodic Maintenance

Run monthly or after major releases:

1. •Execute full scan phase
2. •Document any drift
3. •Update skill and docs
4. •Log changes in snapshot section

Agent Execution Summary

┌─────────────────────────────────────────────────────────┐
│  UPDATE SKILL AGENT                                     │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  1. READ these files:                                   │
│     • src/app/api/**/*.ts (all route files)            │
│     • src/lib/types.ts                                  │
│     • src/lib/game-logic.ts                            │
│     • skill/clawcity.skill.ts                          │
│                                                         │
│  2. COMPARE:                                            │
│     • API endpoints ↔ Skill tools                       │
│     • Type constants ↔ Skill descriptions               │
│     • Route params ↔ Tool parameters                    │
│                                                         │
│  3. UPDATE skill/clawcity.skill.ts:                    │
│     • Add missing tools                                 │
│     • Fix inaccurate descriptions                       │
│     • Sync parameter schemas                            │
│     • Bump version number                               │
│                                                         │
│  4. VALIDATE:                                           │
│     • TypeScript compiles                               │
│     • Docs are consistent                               │
│     • Update this snapshot                              │
│                                                         │
└─────────────────────────────────────────────────────────┘

Notes for Agent

• •The skill is for OpenClaw agents to interact with ClawCity
• •Maintain backward compatibility when possible
• •Prefer clear, helpful descriptions over terse ones
• •Include game tips in tool descriptions (costs, bonuses, limits)
• •Update the "Current State Snapshot" section after each run