Vikunja

Interact with a Vikunja task management instance via its REST API. Use this skill whenever the user wants to manage tasks, projects, labels, assignees, or re...

Security Scan

The skill's requirements and runtime instructions align with its stated purpose (talking to a Vikunja REST API); it is instruction-only and only asks for the Vikunja base URL and API token which are appropriate for this integration.

Purpose & Capability

Name/description (Vikunja API) match the declared env vars (VIKUNJA_BASE_URL, VIKUNJA_API_TOKEN) and the documented endpoints; nothing requested appears unrelated to task management.

Instruction Scope

SKILL.md instructs only how to call the Vikunja REST API, how to handle pagination/errors, and to confirm destructive actions; it does not ask for unrelated files, system creds, or external endpoints.

Install Mechanism

No install spec and no code files (instruction-only). Nothing is downloaded or written to disk by the skill itself.

Credentials

Only two env vars are required: the instance base URL and an API token. These are the minimal, expected credentials for the described API access; primaryEnv is correctly set to VIKUNJA_API_TOKEN.

Persistence & Privilege

always is false and the skill is user-invocable; it does not request permanent presence or access to other skills/config. Autonomous invocation is allowed but is the platform default and not by itself a concern here.

Assessment

This skill is coherent and only needs the Vikunja base URL and an API token to operate. Before installing: (1) ensure the base URL is a trusted Vikunja instance you control or trust; (2) create a token with the minimal scopes needed (avoid full-admin tokens if possible) and store it securely in environment variables, not pasted into chat; (3) be aware the agent will be able to read and modify tasks on that instance, so enable confirmation for destructive actions; (4) monitor the instance's access logs and be prepared to revoke/rotate the API token if you suspect misuse. If you need higher assurance, ask for the skill's implementation code (rather than instruction-only) or run requests through a proxy / audit logs to verify behaviour.

Vikunja Skill

Connects an OpenClaw agent to any Vikunja instance via its REST API (/api/v1). Uses an API token for authentication — no session management needed.

Configuration (required env vars)

Variable	Description
VIKUNJA_BASE_URL	Base URL of the instance, e.g. https://vikunja.example.com
VIKUNJA_API_TOKEN	API token created under Settings → API Tokens

The agent must confirm both vars are set before making any request. If missing, tell the user exactly which var is absent and where to create the token (Settings → API Tokens in the Vikunja web UI).

Important API conventions

Vikunja uses non-standard HTTP verbs:

• PUT = create a new resource
• POST = update an existing resource
• GET = read / list
• DELETE = delete

All requests:

• Header: Authorization: Bearer <VIKUNJA_API_TOKEN>
• Header: Content-Type: application/json
• Base: ${VIKUNJA_BASE_URL}/api/v1

Paginated list endpoints accept ?page=N&per_page=50&s=<search>. Response headers x-pagination-total-pages and x-pagination-result-count tell you if more pages exist.

Supported operations

See references/endpoints.md for the full endpoint reference.

Projects

• List all projects the user has access to
• Create a new project
• Get a single project by ID

Tasks

• List tasks (all, or filtered by project)
• Get a single task by ID
• Create a task in a project
• Update a task (title, description, priority, due date, percent done)
• Mark a task as done ("done": true)
• Delete a task

Labels

• List all available labels
• Create a label
• Add a label to a task
• Remove a label from a task

Assignees

• Add a user as assignee to a task
• Remove an assignee from a task
• List task assignees

Reminders

• Add a reminder to a task (absolute datetime or relative offset)
• Remove a reminder from a task
• Reminders are part of the task object — use the task update flow

Workflow guidelines

1. Resolve names to IDs first. If the user says "add a task to my Work project", list projects and find the ID for "Work" before creating the task.
2. Confirm destructive actions. Before deleting a task or project, confirm with the user.
3. Show structured output. When listing tasks, present title, due date, priority, labels, and done status. Format dates in a human-readable way.
4. Handle pagination. If x-pagination-total-pages > 1, fetch subsequent pages or inform the user that results are truncated.
5. Error handling. On HTTP 4xx/5xx, surface the message field from the JSON response to the user. On 401, remind them to check VIKUNJA_API_TOKEN.

Example interactions

• "What tasks are due this week?" → GET /tasks/all with filter, format results
• "Create a task 'Deploy new release' in my Homelab project due Friday" → resolve project ID, then PUT /projects/{id}/tasks
• "Mark task 42 as done" → POST /tasks/42 with {"done": true}
• "Add the 'urgent' label to task 17" → resolve label ID, PUT /tasks/17/labels
• "Assign me to task 5" → look up current user via GET /user, PUT /tasks/5/assignees
• "Set a reminder for task 8 in 2 hours" → compute absolute datetime, POST /tasks/8

Read references/endpoints.md for exact request/response shapes.