Skillfully API skill

Use this skill to onboard and manage Skillfully from a non-browser AI runtime.

Set this once:

BASE_URL="https://www.skillfully.sh"

1) Login via API code

Call POST /login to start login.

curl -X POST "$BASE_URL/login" \
  -H "content-type: application/json" \
  -d '{"email":"agent@example.com"}'

The response indicates a code was sent. email must be reachable by Skillfully's email delivery webhook.

2) Verify code and get bearer token

Call POST /login_confirm with the code from email.

curl -X POST "$BASE_URL/login_confirm" \
  -H "content-type: application/json" \
  -d '{"email":"agent@example.com","code":"123456"}'

Response shape:

{
  "token_type": "Bearer",
  "access_token": "<jwt-like-token>",
  "token_prefix": "a1b2c3d4",
  "user_id": "api_user_123",
  "token_expires_at": 1745000000000
}

Use access_token for every authenticated endpoint with:

Authorization: Bearer <access_token>

3) Create a tracked skill and receive the suggested snippet

Call POST /skills with name and optional description.

curl -X POST "$BASE_URL/skills" \
  -H "authorization: Bearer <access_token>" \
  -H "content-type: application/json" \
  -d '{"name":"Code Reviewer","description":"Collect feedback after each run"}'

Response shape:

{
  "id": "<record-id>",
  "skill_id": "sk_xxxxxx",
  "name": "Code Reviewer",
  "description": "Collect feedback after each run",
  "feedback_url": "https://www.skillfully.sh/feedback/sk_xxxxxx",
  "snippet": "# Skillfully feedback (required)\n...\nhttps://www.skillfully.sh/feedback/sk_xxxxxx",
  "created_at": 1745000000000
}

Paste snippet into the agent skill you maintain (typically SKILL.md).

4) Retrieve feedback for one skill

Call GET /feedback/<skill_id> with optional query filters:

• rating=positive|negative|neutral (optional)
• sort=asc|desc (optional, default desc)
• limit=1..100 (optional, default 20)
• cursor=<createdAt:id> (optional, required for stable pagination)

curl -X GET "$BASE_URL/feedback/sk_xxxxxx?rating=positive&sort=desc&limit=25" \
  -H "authorization: Bearer <access_token>"

Paginated responses include:

{
  "items": [],
  "sort": "desc",
  "limit": 25,
  "rating": "positive",
  "cursor": null,
  "hasMore": true,
  "nextCursor": "1739999999000:feedback-record-id"
}

Use nextCursor as the cursor query arg for the next call:

curl -X GET "$BASE_URL/feedback/sk_xxxxxx?sort=desc&cursor=1739999999000:feedback-record-id" \
  -H "authorization: Bearer <access_token>"