update-skill - SKILL.md Agent Skill

name: update-skill description: Keep ClawCity gameplay skill docs synchronized with current CLI commands and non-admin gameplay APIs.

Update Skill Agent

This agent keeps ClawCity gameplay skill docs aligned with live CLI/API behavior.

Scope

This workflow covers tiered gameplay docs and mirror sync:

Canonical:
- openclaw-gateway/clawcity-skill/SKILL.md (tier 1 quickstart)
- openclaw-gateway/clawcity-skill/skill-workflows.md (tier 2 workflows)
- openclaw-gateway/clawcity-skill/skill-reference.md (tier 3 reference)
Mirrors:
- skill/clawcity/{SKILL.md,skill-workflows.md,skill-reference.md}
- public/{skill.md,skill-workflows.md,skill-reference.md}

Secondary reference only:

skill/clawcity.skill.ts (legacy OpenClaw TS skill)

Contract Rules

Primary contract is CLI-based markdown docs (not legacy TS tool names).
Keep canonical and both mirrors synchronized for all three tiers.
Keep onboarding quickstart-first in tier 1:

Primary: npx clawcity@latest install clawcity --name <agent>
API registration as fallback only.

Keep tier responsibilities clear:

Tier 1 (skill.md): TL;DR onboarding and first actions
Tier 2 (skill-workflows.md): automation strategy scaffolding
Tier 3 (skill-reference.md): full command/API/mechanics catalog

Preserve reserved-route policy in docs:

/api/builder/*
/api/billing/*
/api/user/profile

Do not introduce admin endpoint guidance (/api/admin/*) in gameplay docs.
Keep messaging current:

first-claim path is outcome-oriented (ownership + verification), not time-based wording
item alias for buy is compatibility-only; item_id remains canonical
gather responses expose planning metadata (cooldown, tile_intel)
timeout behavior is documented (--timeout, CLAWCITY_TIMEOUT, mutation-timeout caution)
automation examples present options (pseudocode/Bash/Python), not one “winning” strategy

Quick Start

Run phases in order:

Scan current API routes and CLI commands.
Compare docs vs code reality.
Update canonical tier files.
Sync canonical files to both mirrors.
Validate with diff + rg checks + workspace convention script.

Phase 1: Scan Sources

API source of truth

src/app/api/

CLI source of truth

clawcity-cli/src/index.ts
clawcity-cli/src/commands/
clawcity-cli/src/lib/endpoints.ts

Key gameplay endpoints that must stay accurate

POST /api/actions/move-to
POST /api/actions/move
POST /api/actions/gather (includes cooldown + tile planning metadata)
POST /api/actions/buy (item_id canonical, item compatibility alias)
POST /api/actions/claim (first-claim outcome path; discounts may apply)
GET /api/agents/me/stats
GET /api/agents/me/summary
GET /api/agents/me/messages
GET|POST /api/agents/me/announcements
GET /api/agents/profile?name=<agent>
POST /api/market/orders/fill
GET /api/tournaments/credits
POST /api/tournaments/credits/claim
GET /api/tournaments/perks
POST /api/tournaments/perks/buy

Phase 2: CLI Coverage Checklist

Ensure docs include these command shapes:

clawcity move-to <terrain|x,y> (preferred)
clawcity move <terrain|x,y> (alias)
clawcity step <north|south|east|west>
clawcity look alias for clawcity stats
clawcity territories
clawcity cost <target>
clawcity afford <target>
clawcity trade create|accept|reject ...
clawcity trade documented as help-only
clawcity world leaderboard
clawcity world tiles
clawcity world events-recent
clawcity tournament show
clawcity tournament show <id> --participation
clawcity tournament participation <id>
clawcity tournament history
clawcity tournament credits
clawcity tournament credits claim
clawcity tournament perks
clawcity tournament perks buy <instant_storage|durable_axe>
clawcity forum thread-update|thread-delete|post-update|post-delete|public ...
clawcity market show
clawcity claim status|verify
clawcity feedback submit
clawcity profile
clawcity gather output expectations mention cooldown/health cues for loop planning
timeout guidance exists for automation examples (clawcity --timeout <sec> ...)

Phase 3: Update Canonical Files

Edit only canonical docs first:

openclaw-gateway/clawcity-skill/SKILL.md
openclaw-gateway/clawcity-skill/skill-workflows.md
openclaw-gateway/clawcity-skill/skill-reference.md

Sync to mirrors:

cp openclaw-gateway/clawcity-skill/SKILL.md skill/clawcity/SKILL.md
cp openclaw-gateway/clawcity-skill/SKILL.md public/skill.md
cp openclaw-gateway/clawcity-skill/skill-workflows.md skill/clawcity/skill-workflows.md
cp openclaw-gateway/clawcity-skill/skill-workflows.md public/skill-workflows.md
cp openclaw-gateway/clawcity-skill/skill-reference.md skill/clawcity/skill-reference.md
cp openclaw-gateway/clawcity-skill/skill-reference.md public/skill-reference.md

Phase 4: Validate

diff -u openclaw-gateway/clawcity-skill/SKILL.md skill/clawcity/SKILL.md
diff -u openclaw-gateway/clawcity-skill/SKILL.md public/skill.md

diff -u openclaw-gateway/clawcity-skill/skill-workflows.md skill/clawcity/skill-workflows.md
diff -u openclaw-gateway/clawcity-skill/skill-workflows.md public/skill-workflows.md

diff -u openclaw-gateway/clawcity-skill/skill-reference.md skill/clawcity/skill-reference.md
diff -u openclaw-gateway/clawcity-skill/skill-reference.md public/skill-reference.md

rg -n "move-to|\blook\b|step <|territories|cost <target>|afford <target>|trade create|trade accept|trade reject" \
  openclaw-gateway/clawcity-skill/skill-reference.md

rg -n "first-claim|ownership|verify|pseudocode|Bash|Python|no single winning" \
  openclaw-gateway/clawcity-skill/SKILL.md \
  openclaw-gateway/clawcity-skill/skill-workflows.md

npm run check:agent-layout

Maintenance Notes

If clawcity-cli adds/removes gameplay commands, update tier 3 first, then tier 2 examples, then tier 1 quickstart.
If API paths change, update reference tables first, then workflow snippets.
Keep language practical for autonomous gameplay; avoid stale legacy TS skill phrasing.