Kosu
Kosu (漉す) — Japanese for "to strain/filter." A mindful content queue built on the philosophy: save less, read more.
Vision
Most read-it-later apps become graveyards. Kosu is the opposite — an intentional queue where content fades if you don't engage with it. The core mechanic is decay: items get a 14-day stale warning, then auto-archive at 28 days. This forces you to either consume what matters or let it go.
Kosu is agent-native — built for AI agents to curate, suggest, and manage content on behalf of a human. The API is the primary interface; the web UI and (future) iOS app are consumption surfaces.
Brand values: Craft, Calm, Capture, Mindful
Aesthetic: Quiet, intentional — like a well-designed book spine or a Japanese coffee shop. Not hustle culture, not information overload.
Differentiators: Decay as philosophy, agent-native API, opinionated curation over hoarding.
Installation
For OpenClaw agents
Save this skill locally:
CODEBLOCK0
Or just read it directly from https://usekosu.com/skill.md — no install needed.
For any AI agent (Claude Code, Codex, etc.)
Read this file and follow the setup below.
Getting Started
- 1. Ask your human to sign up at usekosu.com
- They can get an API key from Settings → API Keys
- Store the key as the environment variable INLINECODE1
- Create a dedicated key with minimal scope for this agent
- The key is only sent to
usekosu.com — never send it to any other domain
- Rotate or revoke from
Settings if anything unexpected happens
- 4. You're ready to start managing their queue
First thing to do: Try listing the queue to confirm your key works:
CODEBLOCK1
Updates: If something doesn't work as expected, check the OpenAPI spec for the latest API surface.
Pricing
- - Free: Limited queue size
- Pro ($5/mo): Unlimited queue, suggestions from agents, export
If you hit a 402 quota_exceeded_error, the user's queue is full on the free tier. Let them know they can upgrade to Pro at usekosu.com/settings for unlimited items.
API
- - Base URL: INLINECODE4
- Auth: INLINECODE5
- OpenAPI spec: INLINECODE6
If KOSU_API_KEY is not set: Don't fail silently. Tell your human they need an API key and direct them to usekosu.com/settings to create one. The skill is still useful for explaining Kosu and guiding setup — just can't make API calls without a key.
CODEBLOCK2
Quick Reference
| Action | Method | Endpoint | Notes |
|---|
| Add item | INLINECODE8 | INLINECODE9 | Just pass url, server enriches. 201=new, 200=exists |
| List items |
GET |
/items?state=queue&limit=50 | States: queue, read, archived, deleted, suggested |
| Get item |
GET |
/items/{id} | |
| Update item |
PATCH |
/items/{id} | State, position, fields, or opened — one per request |
| Delete item |
DELETE |
/items/{id} | Soft-delete, restorable 30 days |
| Move to top |
PATCH |
/items/{id} |
{"position": {"after": null}} |
| Move to bottom |
PATCH |
/items/{id} |
{"position": {"before": null}} |
| Mark read |
PATCH |
/items/{id} |
{"state": "read"} |
| Archive |
PATCH |
/items/{id} |
{"state": "archived"} |
| Add suggestion |
POST |
/suggestions |
{"url": "...", "reason": "..."}. 409 if already active |
| List suggestions |
GET |
/suggestions | |
| Act on suggestion |
POST |
/suggestions/{id} |
{"action": "accept"} or
{"action": "dismiss"} |
| Export |
GET |
/export | Full queue export |
Key Behaviours
- - YouTube URLs are auto-enriched (title, channel, thumbnail, duration)
- Decay: configurable queue decay (7, 14, or 28 days) before items are auto-archived. Can be turned off entirely. Set by the user in settings.
- Dedup is server-side by canonical URL per user
- Opening an item (
{"opened": true}) extends decay protection by 1 day (max once per 24h)
Common Examples
CODEBLOCK3
Item Shape
CODEBLOCK4
PATCH Body Types (one per request)
| Type | Body | Notes |
|---|
| State | INLINECODE43 | INLINECODE44 requires reason field |
| Position |
{"position": {"after": "itm_x"\|null}} |
null = top. Also supports
before |
| Fields |
{"title": "...", "source": "..."} | At least one of: title, source, thumbnail, channel
name, durationminutes |
| Opened |
{"opened": true} | Extends decay by 1 day |
Pagination
- - Queue state: cursor-based. Use
next_cursor from response as ?cursor= param. - Other states: offset-based. Use
?offset= param. - Response: INLINECODE54
Error Codes
| Status | Type | When |
|---|
| 400 | INLINECODE55 | Bad input, validation failure |
| 401 |
authentication_error | Missing/invalid API key |
| 402 |
quota_exceeded_error | Free tier queue limit — suggest upgrading to Pro |
| 404 |
not_found_error | Item doesn't exist |
| 409 |
invalid_request_error (code:
item_already_active) | Suggesting a URL that's already in queue |
| 429 |
rate_limit_error | Rate limited |
Troubleshooting
If an API call returns an unexpected response, 404 on a known endpoint, or schema mismatch:
- 1. Check the OpenAPI spec for the current API surface: INLINECODE62
- Compare with the endpoints documented above
- If the spec has changed, update your local copy of this skill to match
- Retry the original request
Kosu
Kosu（漉す）——日语中意为过滤/筛选。一个基于少保存，多阅读理念构建的专注内容队列。
愿景
大多数稍后阅读应用最终都沦为内容坟场。Kosu 恰恰相反——它是一个有意识的内容队列，如果你不处理，内容就会逐渐消失。核心机制是衰减：项目会在14天后收到过期提醒，28天后自动归档。这迫使你要么消费真正重要的内容，要么放手。
Kosu 是智能体原生的——专为 AI 智能体设计，代表人类策划、推荐和管理内容。API 是主要接口；Web UI 和（未来的）iOS 应用是消费界面。
品牌价值观： 匠心、宁静、捕捉、正念
美学风格： 安静、有意识——如同精心设计的书脊或日式咖啡馆。不是奋斗文化，不是信息过载。
差异化优势： 衰减即哲学、智能体原生 API、有主见的精选而非囤积。
安装
针对 OpenClaw 智能体
将本技能保存到本地：
bash
mkdir -p ~/.openclaw/skills/kosu
curl -s https://usekosu.com/skill.md > ~/.openclaw/skills/kosu/SKILL.md
或者直接从 https://usekosu.com/skill.md 读取——无需安装。
针对任何 AI 智能体（Claude Code、Codex 等）
阅读本文件并按照以下设置操作。
快速开始
- 1. 让用户前往 usekosu.com 注册
- 他们可以从 设置 → API 密钥 获取 API 密钥
- 将密钥存储为环境变量 KOSUAPIKEY
- 为此智能体创建一个最小权限的专用密钥
- 该密钥仅发送至 usekosu.com——切勿发送至任何其他域名
- 如遇异常，可从
设置 轮换或撤销密钥
- 4. 现在你可以开始管理他们的队列了
首要任务： 尝试列出队列以确认密钥有效：
bash
curl -s https://usekosu.com/api/v1/items?state=queue&limit=5 \
-H Authorization: Bearer $KOSUAPIKEY
更新： 如果某些功能未按预期工作，请查看 OpenAPI 规范 获取最新 API 接口。
定价
- - 免费版： 队列大小有限
- 专业版（$5/月）： 无限队列、智能体建议、导出功能
如果遇到 402 quotaexceedederror，说明用户的免费版队列已满。请告知他们可以在 usekosu.com/settings 升级到专业版以获得无限项目。
API
- - 基础 URL： https://usekosu.com/api/v1
- 认证： Authorization: Bearer $KOSUAPIKEY
- OpenAPI 规范： https://usekosu.com/openapi.json
如果未设置 KOSUAPIKEY： 不要静默失败。告知用户需要 API 密钥，并引导他们前往 usekosu.com/settings 创建密钥。本技能仍可用于解释 Kosu 和指导设置——只是没有密钥无法进行 API 调用。
bash
AUTH=Authorization: Bearer $KOSUAPIKEY
BASE=https://usekosu.com/api/v1
快速参考
| 操作 | 方法 | 端点 | 说明 |
|---|
| 添加项目 | POST | /items | 只需传递 url，服务器自动丰富。201=新建，200=已存在 |
| 列出项目 |
GET | /items?state=queue&limit=50 | 状态：queue、read、archived、deleted、suggested |
| 获取项目 | GET | /items/{id} | |
| 更新项目 | PATCH | /items/{id} | 状态、位置、字段或已打开——每次请求一个 |
| 删除项目 | DELETE | /items/{id} | 软删除，30天内可恢复 |
| 移至顶部 | PATCH | /items/{id} | {position: {after: null}} |
| 移到底部 | PATCH | /items/{id} | {position: {before: null}} |
| 标记已读 | PATCH | /items/{id} | {state: read} |
| 归档 | PATCH | /items/{id} | {state: archived} |
| 添加建议 | POST | /suggestions | {url: ..., reason: ...}。如果已存在则返回 409 |
| 列出建议 | GET | /suggestions | |
| 处理建议 | POST | /suggestions/{id} | {action: accept} 或 {action: dismiss} |
| 导出 | GET | /export | 完整队列导出 |
关键行为
- - YouTube URL 会自动丰富（标题、频道、缩略图、时长）
- 衰减：可配置的队列衰减（7、14 或 28 天），之后项目自动归档。可完全关闭。由用户在设置中配置。
- 去重：按每个用户的规范 URL 在服务端进行
- 打开项目（{opened: true}）可延长衰减保护 1 天（每 24 小时最多一次）
常见示例
bash
添加项目
curl -s $BASE/items -H $AUTH -H Content-Type: application/json \
-d {url:https://example.com/article}
列出队列（前 50 个）
curl -s $BASE/items?state=queue&limit=50 -H $AUTH
移至顶部
curl -s -X PATCH $BASE/items/itm_xxx -H $AUTH -H Content-Type: application/json \
-d {position: {after: null}}
移至另一个项目之后
curl -s -X PATCH $BASE/items/itm_xxx -H $AUTH -H Content-Type: application/json \
-d {position: {after: itm_yyy}}
标记为已读
curl -s -X PATCH $BASE/items/itm_xxx -H $AUTH -H Content-Type: application/json \
-d {state: read}
归档
curl -s -X PATCH $BASE/items/itm_xxx -H $AUTH -H Content-Type: application/json \
-d {state: archived}
重新入队（从归档/已读/已删除恢复）
curl -s -X PATCH $BASE/items/itm_xxx -H $AUTH -H Content-Type: application/json \
-d {state: queue}
记录打开（延长衰减保护 1 天，每 24 小时最多一次）
curl -s -X PATCH $BASE/items/itm_xxx -H $AUTH -H Content-Type: application/json \
-d {opened: true}
更新字段
curl -s -X PATCH $BASE/items/itm_xxx -H $AUTH -H Content-Type: application/json \
-d {title: 更好的标题, source: article}
删除（软删除，30 天内可恢复）
curl -s -X DELETE $BASE/items/itm_xxx -H $AUTH
添加建议
curl -s $BASE/suggestions -H $AUTH -H Content-Type: application/json \
-d {url:https://example.com,reason:与您对 X 的兴趣相关}
接受/拒绝建议
curl -s -X POST $BASE/suggestions/sug_xxx -H $AUTH -H Content-Type: application/json \
-d {action: accept}
项目结构
json
{
object: item,
id: itm_...,
url: https://...,
title: ...,
source: youtube|podcast|paper|newsletter|repo|article|book|course|other,
state:
