Skill: rare-sors/to-agent-service-designer (version 1.0.0)

--- name: toa-service-designer description: > Design, analyze, or document products where AI agents are the primary operator. Use this skill whenever the user asks to design a SaaS, API, platform, or tool that agents will discover and use autonomously — not just a product humans click through. Also use when reviewing existing product specs for agent-readiness, or when the user says "agent-native", "ToA", "agent service", or "skill spec". --- # To-Agent Service Designer Use this skill to design, analyze, or document products primarily used by AI agents. ## Core model Always assume the primary operator is an AI agent, not a human. Humans usually: - provide the goal - own the agent - approve sensitive actions - review results The common interaction model is: - the human gives a one-line prompt to an agent - the agent discovers and uses the service - ongoing usage happens in IM / chat threads - the web UI is mainly for visibility, approval, and control Do not design the product like a normal SaaS where humans click through the main workflow. ## Defaults Start from: - agent entrypoints - IM-based usage - skills, docs, APIs, and auth - task lifecycle - review / approval points - trust and safety boundaries Not from: - pages - feature lists - dashboard-first thinking - chat UI as the product itself ## Required thinking order 1. What is the agent trying to get done? 2. How does the human introduce the service to the agent? 3. What does the agent read first? 4. How does the agent authenticate or prove authority? 5. What task/state model does the service expose? 6. Where must control return to a human? 7. What backend is required? 8. What frontend is required? 9. What trust and safety controls are required? ## Required output structure ### 1. VISION - what the service is - what layer of the agent stack it belongs to - why it is agent-native, not human-first ### 2. Frontend - what humans need to see - what humans need to approve - why frontend is only a control surface ### 3. Onboarding - how a human introduces the service to an agent - the first agent-readable entrypoint - what the agent can do autonomously - what requires claim, review, or approval ### 4. Backend - MVP architecture - what can be done with Next.js-only - what should later become workers or separate services ### 5. Skill Spec The Skill Spec is the most important artifact in any agent-native service. It is the contract between the service and every agent that will ever use it. Design it as a multi-file bundle, not a single document. #### 5a. File bundle Define each file in the bundle. Every service needs at minimum: | File | URL pattern | Purpose | |------|-------------|---------| | `SKILL.md` | `https://yourservice.com/skill.md` | Entry point. Agent reads this first. Contains overview, install block, auth flow, and capability summary. | | `auth.md` | `https://yourservice.com/auth.md` | Full auth contract: how the agent registers, where credentials are stored, how tokens are rotated, what the human must approve. | | `openapi.json` | `https://yourservice.com/openapi.json` | Machine-readable API surface. The agent uses this to discover endpoints, required params, and response shapes. | | `package.json` / `skill.json` | `https://yourservice.com/skill.json` | Versioned metadata: name, version, api_base, category, homepage. | Optional files to add as the service grows: | File | Purpose | |------|---------| | `heartbeat.md` | How the agent wires this service into its periodic check-in loop. Include timing, state tracking, and what to do on each cycle. | | `rules.md` | Rate limits, content policies, trust tiers, and hard NEVER rules. Keep separate so agents can re-fetch without reloading the full skill. | | `messaging.md` | DM / notification / webhook patterns for async interaction. | | `developers.md` | For agents building on or extending the service. Include webhook schemas, event types, SDK notes. | #### 5b. SKILL.md structure (the entry point) The top-level `SKILL.md` an agent fetches must contain: 1. **YAML frontmatter** — `name`, `version`, `description`, `homepage`, `metadata` (with `api_base`, `category`, `emoji`). 2. **Skill files table** — list every file in the bundle with its URL. Agents load additional files on demand. 3. **Install block** — copy-pasteable `curl` commands to install the full bundle locally. Also note that agents can read files directly from URLs without installing. 4. **Security contract** — a `CRITICAL SECURITY WARNING` block near the top. List the exact domain the API key must never leave. Use NEVER/REFUSE language. The agent must see this before it sees the API docs. 5. **Registration / first-run** — the minimal API call to create an identity. Show the full response shape including where the API key lives, what the `claim_url` is for, and what the human must do. 6. **Credential storage** — show the agent exactly where and how to persist its key (`~/.config/<service>/credentials.json` or env var). 7. **Auth pattern** — one representative `curl` with `Authorization: Bearer` header. 8. **Capability summary table** — every action the agent can take, one line each, with a priority signal (`🔴 Do first`, `🟠 High`, `🟡 Medium`, `🔵 When ready`). 9. **Core API sections** — grouped by resource. Each section: one purpose sentence, the minimal `curl` example, key fields in the response, and common error shapes. 10. **Human-agent bond** — a short section explaining how ownership and verification work. What does the human do? What does the agent do? What is the trust handoff? #### 5c. Frontmatter metadata schema ```yaml --- name: service-name version: 1.0.0 description: One sentence. What the agent can do with this service. homepage: https://yourservice.com metadata: emoji: 🔧 category: productivity # social | dev | data | productivity | finance | ... api_base: https://yourservice.com/api/v1 --- ``` #### 5d. Agent-first writing rules for skill files - Write for the agent, not a human reader. Assume the agent has no context beyond what is in the file. - Use imperative language: "Register first", "Save your API key immediately", "NEVER send your key to any other domain". - Include `⚠️` and `🔒` signals for critical constraints. Agents parse tone and emphasis. - Every API example must be a working `curl`. No pseudocode. - Every response example must be real JSON, not a simplified sketch. - State expiry times, rate limits, and cooldowns explicitly. Agents need these to plan retries. - Include a `what_to_do_next` or priority table so agents know where to start on each check-in. - Keep `SKILL.md` under 500 lines. Offload detail to `rules.md`, `heartbeat.md`, etc. Add a table of contents if over 200 lines. #### 5e. Heartbeat integration spec If the service expects periodic or ongoing agent engagement, define a heartbeat contract: ```markdown ## Mycheckservice (every 30 minutes) If 30 minutes since last check: 1. Fetch https://yourservice.com/heartbeat.md and follow it 2. Update lastCheck timestamp in memory ``` The `heartbeat.md` file should: - Start with a `/home` or `/dashboard` call that returns a prioritised action list - Tell the agent what to do in order (respond to activity first, then browse, then post) - Include state-tracking instructions (`lastCheck`, `pendingItems`, etc.) - Be fetchable independently so the agent gets updated instructions without reloading the full skill #### 5f. Verification and anti-abuse patterns For services where agents take write actions, define the verification contract in SKILL.md: - What triggers a challenge (new accounts, first N actions, suspicious patterns) - The challenge format (math, captcha, proof-of-work) - How the agent submits the answer - What "trusted agent" status means and how it is earned - What suspension means and how the agent surfaces this to its human ### 6. Identity / Auth - who owns the agent - how the agent is verified - how delegated authority works - how tokens, claims, or approvals work ### 7. Task Flow - the core state machine - waiting states - approval checkpoints - artifacts, outputs, and handoff rules ### 8. Trust & Safety - prompt injection - spoofed or malicious agents - permission boundaries - audit logs - sandboxing or approval-gated actions ## Mandatory checks Revise the design if: - the main flow is humans clicking through pages - there is no clear agent entrypoint - ongoing usage is not IM-first - auth only considers humans - task flow is fully synchronous and unrealistic - approval / handoff is missing - frontend is treated as the product core - trust and safety is shallow - SKILL.md has no install block - SKILL.md has no security contract before the API docs - there is no capability summary table - the skill bundle is a single file with no separation of concerns ## Output rules Be concrete. Prefer: - flows - interfaces - state transitions - approval points - skill/docs/API surfaces Always include: - one sentence for the human role - one sentence for the agent role - one agent-readable entrypoint (a live URL the agent can `curl`) - one IM-based interaction loop - one core task flow - one approval checkpoint - one key safety risk - a full skill bundle file table (name, URL, purpose) - a SKILL.md outline showing all required sections in order ## Common build stack Default MVP stack: - Next.js - Vercel - Supabase - GitHub Use Impeccable when strong UI / frontend design guidance is needed. Do not introduce heavier infra unless task flow requires it. ## Common skill references GitHub - https://github.com/openclaw/openclaw/blob/main/skills/github/SKILL.md Supabase - https://github.com/openclaw/skills/blob/main/skills/stopmoclay/supabase/SKILL.md Vercel - npx skills add vercel-labs/agent-skills --skill vercel-deploy Impeccable - https://github.com/pbakaus/impeccable Next.js Best Practices - https://skills.sh/vercel-labs/next-skills/next-best-practices

path: README.md
content: # To-Agent Service Designer

> Design products where **AI agents** are the primary operator — not humans.

![License](https://img.shields.io/github/license/Rare-Sors/To-Agent-Service_Designer-Skill)
![Stars](https://img.shields.io/github/stars/Rare-Sors/To-Agent-Service_Designer-Skill)
![Skill](https://img.shields.io/badge/skill-ready-brightgreen)
![Agent](https://img.shields.io/badge/agent-native-purple)

## What is this skill?

This skill guides you to design **agent-native services** — products where AI agents are the primary operators, not humans. Humans provide goals, own agents, approve sensitive actions, and review results; agents discover services, authenticate, execute tasks, and handle ongoing work via IM/chat.

Key principles:
- Design from **agent entrypoints** first, not dashboard-first
- Use **Skill Spec** (file bundle) as the contract between services and agents
- **IM-native** interaction — chat/IM as primary workflow, web UI for visibility/approval only
- Built-in **Trust & Safety** — auth, approval checkpoints, anti-abuse patterns

## Quick Start

```sh
# Download the skill file
curl -L https://raw.githubusercontent.com/Rare-Sors/To-Agent-Service_Designer-Skill/main/SKILL.md -o SKILL.md
```

## Features

- **Agent-first** — Design from agent perspective, not dashboard-first
- **Skill Spec** — Structured file bundle contract for services & agents
- **IM-native** — Chat/IM as primary interaction, not web UI
- **Trust & Safety** — Built-in auth, approval, and anti-abuse patterns

## Skill Spec Structure

| File | Purpose |
|------|---------|
| `SKILL.md` | Agent entry point — overview, auth, capabilities |
| `auth.md` | Full authentication contract |
| `openapi.json` | Machine-readable API surface |
| `skill.json` | Versioned metadata |

## Design Flow

```
Vision → Onboarding → Backend → Skill Spec → Auth → Task Flow → Trust & Safety
```

## Default Stack

Next.js · Vercel · Supabase · GitHub

## Contributing

Contributions welcome!

1. Fork the repo
2. Create feature branch (`git checkout -b feature/amazing-feature`)
3. Commit changes (`git commit -m 'Add amazing feature'`)
4. Push to branch (`git push origin feature/amazing-feature`)
5. Open Pull Request

## Links

- **GitHub:** [Rare-Sors/To-Agent-Service_Designer-Skill](https://github.com/Rare-Sors/To-Agent-Service_Designer-Skill)
- **Issues:** [Report a bug](https://github.com/Rare-Sors/To-Agent-Service_Designer-Skill/issues)

## License

MIT

---

🌐 [中文文档](README.zh.md)


path: README.zh.md
content: # To-Agent 服务设计器

> 为 **AI 代理** 作为主要操作者设计产品 —— 而非人类。

![License](https://img.shields.io/github/license/Rare-Sors/To-Agent-Service_Designer-Skill)
![Stars](https://img.shields.io/github/stars/Rare-Sors/To-Agent-Service_Designer-Skill)
![Skill](https://img.shields.io/badge/skill-ready-brightgreen)
![Agent](https://img.shields.io/badge/agent-native-purple)

## 这是什么？

本技能指导你设计 **agent-native 服务** —— AI 代理作为主要操作者的产品，而非人类。人类提供目标、拥有代理、审批敏感操作、审查结果；代理发现服务、认证身份、执行任务、通过 IM/聊天处理持续工作。

核心原则：
- 从 **代理入口点** 出发设计，而非仪表盘优先
- 使用 **技能规范**（文件束）作为服务与代理之间的契约
- **IM 原生** 交互 — 聊天/IM 为主要工作流，Web UI 仅用于可视化和审批
- 内置 **信任与安全** — 认证、审批检查点、反滥用模式

## 快速开始

```sh
# 下载技能文件
curl -L https://raw.githubusercontent.com/Rare-Sors/To-Agent-Service_Designer-Skill/main/SKILL.md -o SKILL.md
```

## 特性

- **代理优先** — 从代理视角设计，而非仪表盘优先
- **技能规范** — 服务与代理之间的结构化文件束契约
- **IM 原生** — 聊天/即时通讯为主要交互界面，而非 Web UI
- **信任与安全** — 内置认证、审批和反滥用模式

## 技能规范结构

| 文件 | 用途 |
|------|------|
| `SKILL.md` | 代理入口点 — 概览、认证、能力 |
| `auth.md` | 完整认证契约 |
| `openapi.json` | 机器可读的 API 表面 |
| `skill.json` | 版本化元数据 |

## 设计流程

```
愿景 → 引导 → 后端 → 技能规范 → 认证 → 任务流 → 信任与安全
```

## 默认技术栈

Next.js · Vercel · Supabase · GitHub

## 贡献

欢迎贡献！

1. Fork 仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 发起 Pull Request

## 链接

- **GitHub:** [Rare-Sors/To-Agent-Service_Designer-Skill](https://github.com/Rare-Sors/To-Agent-Service_Designer-Skill)
- **Issues:** [报告问题](https://github.com/Rare-Sors/To-Agent-Service_Designer-Skill/issues)

## 许可证

MIT

---

🌐 [English](README.md)


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)