Vikunja Fast (阿山自用版)

Manage Vikunja projects and tasks (overdue/due/today), mark done, and get quick summaries via the Vikunja API.

Security Scan

The skill's files, instructions, and required credentials are consistent with a Vikunja CLI helper — nothing in the package appears to request unrelated access or contact unexpected endpoints.

Purpose & Capability

Name/description match the implementation: the script and SKILL.md only implement Vikunja API operations (list/create/update/delete tasks and projects). Required binaries (curl, jq) and the declared env var (VIKUNJA_URL) and primary credential (VIKUNJA_TOKEN) are appropriate for this purpose. Minor metadata mismatch: _meta.json lists a different ownerId and version (1.0.0) than the registry metadata (ownerId kn781..., version 2.0.0), which may indicate repackaging or that the manifest wasn't updated.

Instruction Scope

Runtime instructions and the included vikunja.sh call only Vikunja endpoints derived from VIKUNJA_URL (normalized to /api/v1). The script reads only the declared env vars (VIKUNJA_URL, VIKUNJA_TOKEN, VIKUNJA_USERNAME, VIKUNJA_PASSWORD) and does not reference other system files, other services, or external endpoints.

Install Mechanism

There is no install spec (instruction-only with one helper script). Nothing is downloaded or written to disk by an installer. The included shell script is plain and readable; no archive downloads or external installers are present.

Credentials

Requested environment variables are proportional: VIKUNJA_URL is required and VIKUNJA_TOKEN (primary) or username/password are appropriate for authenticating to Vikunja. The requests do not include unrelated credentials or excessive env access. Consider limiting token scope or using an account with minimal privileges if possible.

Persistence & Privilege

The skill does not request always:true and does not modify other skills or system-wide configuration. It can be invoked autonomously (platform default), which would allow the skill to perform create/update/delete actions against the provided Vikunja instance using the token — this is expected behavior but worth noting.

Assessment

This skill appears to do exactly what it says: a small shell helper that calls your Vikunja instance. Before installing, verify the VIKUNJA_URL you provide is a trusted Vikunja server (the script will send your token or username/password to that URL). Prefer supplying a limited-scope API token (or a dedicated test account) rather than an administrator token, because the skill can create/update/delete tasks and projects when invoked. Note the package metadata mismatch (_meta.json owner/version differs from registry metadata) — if provenance is important, confirm the publisher/source. Finally, as with any credential use, store your token securely (environment or secrets store) and rotate it if you stop using the skill.

✅ Vikunja Fast Skill (v2 API)

Use Vikunja as the source of truth for all task management. This skill supersedes any internal working-buffer tracking for user-visible tasks.

API Base

• Base URL: $VIKUNJA_URL/api/v1（自动规范化）
• Auth: JWT Bearer token（Authorization: Bearer <token>）
• Token 获取: POST /login（用户名字段是 username）

Critical API Differences（必须记住）

操作	正确方法
创建项目	PUT /projects（PUT，不是 POST）
更新项目	POST /projects/{id}（POST）
创建任务	PUT /projects/{id}/tasks（PUT，不是 POST）
更新任务（含标记完成）	POST /tasks/{id}
获取所有任务	GET /tasks（不是 /tasks/all）
删除任务	DELETE /tasks/{id}
移动任务到看板桶	POST /projects/{project}/views/{view}/buckets/{bucket}/tasks

Setup

# 环境变量（推荐写入 secure/api-fillin.env）
VIKUNJA_URL=http://192.168.8.11:3456
VIKUNJA_TOKEN=tk_xxxx   # API Token 或 JWT

Quick Commands

# 登录获取 JWT（如果只有用户名密码）
curl -X POST "$VIKUNJA_URL/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"USER","password":"PASS","long_token":true}' | jq

# 列出所有项目
curl -s "$VIKUNJA_URL/projects" -H "Authorization: Bearer $VIKUNJA_TOKEN" | jq '.[] | {id,title}'

# 列出所有开放任务
curl -s "$VIKUNJA_URL/tasks" -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  | jq '.[] | select(.done == false) | {id,.title,due_date: .due_date,project_id}'

# 创建项目（PUT /projects）
curl -X PUT "$VIKUNJA_URL/projects" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"项目名称","description":"","identifier":"","hex_color":""}' | jq '{id,title}'

# 在项目中创建任务（PUT /projects/{id}/tasks）
curl -X PUT "$VIKUNJA_URL/projects/9/tasks" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"任务标题","description":"","due_date":"2026-04-30T23:59:00Z"}' | jq '{id,title}'

# 标记任务完成（POST /tasks/{id}）
curl -X POST "$VIKUNJA_URL/tasks/123" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"done": true}' | jq '{id,done,done_at}'

# 更新任务（POST /tasks/{id}，可改 project_id 移动任务）
curl -X POST "$VIKUNJA_URL/tasks/123" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project_id":9,"title":"新标题"}' | jq '{id,project_id,title}'

# 删除任务（DELETE /tasks/{id}）
curl -X DELETE "$VIKUNJA_URL/tasks/123" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN"

# 批量更新任务
curl -X POST "$VIKUNJA_URL/tasks/bulk" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tasks":[{"id":1,"done":true},{"id":2,"done":true}]}' | jq

Helper CLI（vikunja.sh）

# 列出开放任务（按到期时间排序）
vikunja.sh list --filter 'done = false'

# 逾期任务
vikunja.sh overdue

# 今日到期
vikunja.sh due-today

# 查看任务详情
vikunja.sh show 123

# 标记完成
vikunja.sh done 123

# 创建任务
vikunja.sh create 9 "新任务标题"

# 删除任务
vikunja.sh delete 123

Task Display Format

每个任务输出格式：

<EMOJI> <DUE_DATE> - #<ID> <TASK>

• Emoji：项目标题首字符（中文/英文标题第一个非字母数字token）
• 无 Emoji 时默认 🔨
• 无到期日显示 (no due)

Filtering Syntax

Vikunja filter 示例：

done = false
done = false && due_date < now
done = false && project_id = 9
done = false && due_date >= now/d && due_date < now/d + 1d

完整文档：https://vikunja.io/docs/filters/

Task Model（重要字段）

{
  "id": 123,
  "title": "任务标题",
  "description": "",
  "done": false,
  "done_at": null,
  "due_date": "2026-04-30T15:59:00Z",
  "project_id": 9,
  "repeat_after": 0,
  "priority": 0,
  "start_date": "0001-01-01T00:00:00Z",
  "end_date": "0001-01-01T00:00:00Z",
  "hex_color": "",
  "percent_done": 0,
  "created": "2026-03-31T12:00:00Z",
  "updated": "2026-03-31T12:00:00Z"
}

注意：due_date 为 0001-01-01T00:00:00Z 表示无期限。