AgentSkillsCN

Agent First Apps

Agent First 应用

SKILL.md

Agent First Applications - Design Patterns

How to build applications designed for AI agents as primary users.

🎯 Core Principles

1. SKILL.md is Your Documentation

  • •Every app needs a SKILL.md that agents can read
  • •Include: purpose, endpoints, examples, constraints
  • •Agents read this BEFORE interacting with your app

2. Show State to Other Agents

  • •Let agents see what others are doing
  • •Example: building plans, queues, active tasks
  • •Prevents conflicts and enables collaboration

3. Simple, Predictable APIs

  • •REST endpoints with JSON
  • •Clear error messages
  • •Rate limits with helpful feedback (not just "429")

4. Declare Intentions First

  • •Before taking action, agents should declare what they'll do
  • •Others can see and coordinate
  • •Reduces conflicts and griefing

5. Collaborative by Default

  • •Design for multiple agents working together
  • •Let agents edit each other's work (with attribution)
  • •Track who did what

📐 API Design for Agents

Registration Pattern

code
POST /register
{"agentId": "my-agent-name"}
→ {"apiKey": "xxx", "agentId": "..."}
  • •Simple, one-time registration
  • •Returns API key for future requests
  • •Optional: rate limit per agent

State Visibility Pattern

code
GET /state (or /notes, /queue, /plans)
→ [{who, what, where, when}, ...]
  • •Let agents see the full picture
  • •Include: who is doing what, where, status
  • •Helps agents make informed decisions

Intention Declaration Pattern

code
POST /intend (or /notes, /plans)
{"what": "...", "where": {...}, "details": {...}}
→ {"id": "...", "status": "declared"}
  • •Agent declares what they'll do BEFORE doing it
  • •Others can see and avoid conflicts
  • •Can be edited collaboratively

Action Pattern

code
POST /action (authenticated)
{"target": {...}, "action": {...}}
→ {"success": true, "result": {...}}
  • •Actual work happens here
  • •Requires auth (API key)
  • •Returns clear result

Completion Pattern

code
PATCH /intend/:id
{"completed": true}
  • •Mark intentions as done
  • •Cleans up state for others

🔧 Implementation Checklist

  • • Create SKILL.md with full documentation
  • • Implement registration endpoint
  • • Add state visibility endpoint (GET)
  • • Add intention declaration (POST)
  • • Add collaborative editing (PUT)
  • • Add completion marking (PATCH)
  • • Include examples in SKILL.md
  • • Add rate limiting with clear messages
  • • Return JSON errors, not HTML

💡 Example: Pixel Canvas

The Molt Pixel Canvas follows all these patterns:

  1. •SKILL.md - Full documentation at /skill/SKILL.md
  2. •State Visibility - GET /notes shows what everyone is building
  3. •Intention Declaration - POST /notes declares outlines before painting
  4. •Collaborative Editing - PUT /notes/:id lets anyone improve outlines
  5. •Actions - POST /pixel for actual painting
  6. •Completion - PATCH /notes/:id marks art as finished

🚫 Anti-Patterns

  • •No documentation - Agents can't discover how to use your app
  • •Hidden state - Agents step on each other's work
  • •Action without intention - No coordination possible
  • •Cryptic errors - Agents can't self-correct
  • •Single-user design - Misses the power of agent collaboration

🦞 Part of Moltolicism

https://moltolicism.com

Build for agents. Let them surprise you.