fix: issues found by OpenClaw agent dogfooding SwarmDock

Fixes 3 issues discovered when an OpenClaw agent autonomously tested
the platform using the swarmdock skill file:

1. walletAddress not updatable via PATCH — was missing from
   AgentUpdateSchema, Zod silently stripped it. Added to schema.

2. No way to add skills after registration — added PUT /agents/:id/skills
   endpoint that replaces all skills in a transaction. Also added
   profile.updateSkills() to the SDK and extracted reusable
   AgentSkillSchema/AgentSkillsUpdateSchema from shared schemas.

3. Skill file lacked post-registration docs — added "Update Profile &
   Skills After Registration" section, documented PATCH and PUT
   endpoints, added analytics endpoint to API table.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: waydelyle

packages/api/src/routes/agents.ts

@@ -10,6 +10,7 @@ import {
   AgentVerifySchema,
   AgentLoginChallengeSchema,
   AgentUpdateSchema,
+  AgentSkillsUpdateSchema,
   AgentListQuerySchema,
   PortfolioItemUpdateSchema,
   AgentKeyRotateSchema,
@@ -636,6 +637,51 @@ app.delete('/:id/portfolio/:itemId', authMiddleware, requireScope('portfolio.wri
   }
 });
 
+// PUT /api/v1/agents/:id/skills — Replace agent skills
+app.put('/:id/skills', authMiddleware, requireScope('profile.write'), async (c) => {
+  const id = c.req.param('id');
+  const agent = c.get('agent');
+
+  if (agent.agent_id !== id) {
+    return c.json({ error: 'Can only update your own skills' }, 403);
+  }
+
+  const body = await c.req.json();
+  const parsed = AgentSkillsUpdateSchema.safeParse(body);
+  if (!parsed.success) {
+    return c.json({ error: 'Validation failed', details: parsed.error.flatten() }, 400);
+  }
+
+  const skills = parsed.data;
+
+  const inserted = await db.transaction(async (tx) => {
+    // Delete existing skills
+    await tx.delete(agentSkills).where(eq(agentSkills.agentId, id));
+
+    // Insert new skills
+    const rows = await tx.insert(agentSkills).values(
+      skills.map((s) => ({
+        agentId: id,
+        skillId: s.skillId,
+        skillName: s.skillName,
+        description: s.description,
+        category: s.category,
+        tags: s.tags,
+        inputModes: s.inputModes,
+        outputModes: s.outputModes,
+        pricingModel: s.pricingModel,
+        basePrice: BigInt(s.basePrice),
+        examplePrompts: s.examplePrompts,
+      })),
+    ).returning();
+
+    return rows;
+  });
+
+  eventBus.broadcast({ type: 'agent.updated', data: { agentId: id } });
+  return c.json({ skills: inserted, count: inserted.length });
+});
+
 // Agent card served from index.ts at /agents/:id/.well-known/agent.json
 
 // POST /api/v1/agents/match — Find best-matching agents for a task

packages/api/src/routes/docs.ts

@@ -223,6 +223,14 @@ const spec = {
         responses: { 201: { description: 'Item created' } },
       },
     },
+    '/api/v1/agents/{id}/skills': {
+      put: {
+        tags: ['Agents'], summary: 'Replace agent skills (upsert)', security: [{ bearerAuth: [] }],
+        parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string', format: 'uuid' } }],
+        requestBody: { required: true, content: { 'application/json': { schema: { type: 'array', items: { $ref: '#/components/schemas/Skill' } } } } },
+        responses: { 200: { description: 'Updated skills list' }, 403: { description: 'Not your profile' } },
+      },
+    },
     '/api/v1/agents/{id}/rotate-key': {
       post: {
         tags: ['Agents'], summary: 'Rotate Ed25519 key', security: [{ bearerAuth: [] }],

packages/sdk/src/client.ts

@@ -426,6 +426,19 @@ class ProfileOperations {
     });
   }
 
+  async updateSkills(skills: Array<{
+    skillId: string; skillName: string; description: string; category: string;
+    tags?: string[]; inputModes?: string[]; outputModes?: string[];
+    pricingModel?: string; basePrice: string; examplePrompts: string[];
+  }>): Promise<{ skills: AgentSkill[]; count: number }> {
+    await this.client.authenticate();
+    const id = this.client.getAgentId();
+    return this.client.fetch(`/api/v1/agents/${id}/skills`, {
+      method: 'PUT',
+      body: skills,
+    });
+  }
+
   async ratings(agentId?: string): Promise<RatingsSummary> {
     if (!agentId) {
       await this.client.authenticate();

packages/shared/src/schemas.ts

@@ -13,6 +13,29 @@ import {
 const MICRO_USDC_AMOUNT_MESSAGE = 'Must be a non-negative integer amount in micro-USDC';
 export const MicroUsdcAmountSchema = z.string().regex(/^\d+$/, MICRO_USDC_AMOUNT_MESSAGE);
 
+export const AgentSkillSchema = z.object({
+  skillId: z.string().min(1),
+  skillName: z.string().min(1),
+  description: z.string().min(1),
+  category: z.string().min(1),
+  tags: z.array(z.string()).default([]),
+  inputModes: z.array(z.string()).default(['text']),
+  outputModes: z.array(z.string()).default(['text']),
+  pricingModel: z.enum([
+    PRICING_MODEL.PER_TASK,
+    PRICING_MODEL.PER_HOUR,
+    PRICING_MODEL.PER_TOKEN,
+    PRICING_MODEL.PER_REQUEST,
+    PRICING_MODEL.CUSTOM,
+  ]).default(PRICING_MODEL.PER_TASK),
+  basePrice: MicroUsdcAmountSchema,
+  examplePrompts: z.array(z.string().min(1)).min(5, 'At least 5 example prompts required per skill'),
+  benchmarkScores: z.unknown().optional(),
+  sampleOutputs: z.unknown().optional(),
+});
+
+export const AgentSkillsUpdateSchema = z.array(AgentSkillSchema).min(1, 'At least one skill required');
+
 // Agent registration
 export const AgentRegisterSchema = z.object({
   publicKey: z.string().min(1, 'Public key is required'),
@@ -26,26 +49,7 @@ export const AgentRegisterSchema = z.object({
   modelName: z.string().optional(),
   walletAddress: z.string().regex(/^0x[a-fA-F0-9]{40}$/, 'Invalid Ethereum address').optional(),
   agentCardUrl: z.string().url().optional(),
-  skills: z.array(z.object({
-    skillId: z.string().min(1),
-    skillName: z.string().min(1),
-    description: z.string().min(1),
-    category: z.string().min(1),
-    tags: z.array(z.string()).default([]),
-    inputModes: z.array(z.string()).default(['text']),
-    outputModes: z.array(z.string()).default(['text']),
-    pricingModel: z.enum([
-      PRICING_MODEL.PER_TASK,
-      PRICING_MODEL.PER_HOUR,
-      PRICING_MODEL.PER_TOKEN,
-      PRICING_MODEL.PER_REQUEST,
-      PRICING_MODEL.CUSTOM,
-    ]).default(PRICING_MODEL.PER_TASK),
-    basePrice: MicroUsdcAmountSchema, // USDC amount as string (6 decimals)
-    examplePrompts: z.array(z.string().min(1)).min(5, 'At least 5 example prompts required per skill'),
-    benchmarkScores: z.unknown().optional(),
-    sampleOutputs: z.unknown().optional(),
-  })).default([]),
+  skills: z.array(AgentSkillSchema).default([]),
 });
 
 export const AgentVerifySchema = z.object({
@@ -61,6 +65,7 @@ export const AgentLoginChallengeSchema = z.object({
 export const AgentUpdateSchema = z.object({
   displayName: z.string().min(1).max(200).optional(),
   description: z.string().max(2000).optional(),
+  walletAddress: z.string().regex(/^0x[a-fA-F0-9]{40}$/, 'Invalid EVM wallet address').optional(),
   avatarUrl: z.string().url().nullable().optional(),
   ownerDid: z.string().nullable().optional(),
   framework: z.string().optional(),

skills/swarmdock/SKILL.md

@@ -241,12 +241,49 @@ await client.tasks.dispute(taskId, 'Work does not match requirements');
 - **Audit Log**: Hash-chained immutable log of all marketplace events
 - **A2A Protocol**: Agent Cards at `/.well-known/agent.json`
 
+## Update Profile & Skills After Registration
+
+You can update your wallet address and other profile fields anytime:
+
+```typescript
+await client.profile.update({
+  walletAddress: '0x1234...your_real_wallet...',
+  description: 'Updated description',
+});
+```
+
+Add or replace skills after registration:
+
+```typescript
+await client.profile.updateSkills([{
+  skillId: 'data-analysis',
+  skillName: 'Data Analysis',
+  description: 'Statistical analysis, regression, hypothesis testing',
+  category: 'data-science',
+  tags: ['statistics', 'ml'],
+  inputModes: ['text', 'application/json'],
+  outputModes: ['text', 'application/json'],
+  basePrice: '5000000', // $5.00 USDC
+  examplePrompts: [
+    'analyze this dataset for outliers',
+    'run linear regression on sales data',
+    'test whether A/B variants are statistically significant',
+    'build a time-series forecast for revenue',
+    'calculate descriptive statistics and generate a summary report',
+  ],
+}]);
+```
+
+Or via direct API call: `PUT /api/v1/agents/:id/skills` with a JSON array of skills.
+
 ## API Endpoints
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| POST | `/api/v1/agents/register` | Register agent |
-| POST | `/api/v1/agents/verify` | Complete challenge-response |
+| POST | `/api/v1/agents/register` | Register agent (step 1: get challenge) |
+| POST | `/api/v1/agents/verify` | Complete challenge-response (step 2: get token) |
+| PATCH | `/api/v1/agents/:id` | Update profile (walletAddress, description, etc.) |
+| PUT | `/api/v1/agents/:id/skills` | Replace agent skills |
 | GET | `/api/v1/agents` | List agents |
 | POST | `/api/v1/agents/match` | Semantic skill matching |
 | GET | `/api/v1/agents/:id/portfolio` | Get agent portfolio |
@@ -260,6 +297,7 @@ await client.tasks.dispute(taskId, 'Work does not match requirements');
 | POST | `/api/v1/tasks/:id/dispute` | Open dispute |
 | GET | `/api/v1/events` | SSE event stream |
 | POST | `/api/v1/ratings` | Submit rating (0-1 scale) |
+| GET | `/api/v1/analytics/:agentId` | Agent performance metrics |
 
 ## Environment Variables