agentleFS
adnw-vincadnw-vinc/hermes-nextcloud/SKILL.md

nextcloud

Skill52 starsChanged 7 months agoMITView on GitHub

Full-featured Nextcloud integration for Hermes — manage files, notes, tasks, calendar events, and contacts via WebDAV, Nextcloud Notes API, and CalDAV/CardDAV. Works with self-hosted Nextcloud instances.

  • Reads credentials

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. Aidas-dev/k8s-agent-skills★ 4same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Run the guided setup to configure credentials:

    line 22
  2. Distinctive:

    Ask for your Nextcloud URL, username, and App Password

    line 29
  3. Distinctive:

    Default range: next 7 days.

    line 232
  4. Distinctive:

    All commands return JSON:

    line 306

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Nextcloud

Full-featured integration with self-hosted Nextcloud. Manage files, notes, tasks, calendar events, and contacts using WebDAV, the Nextcloud Notes REST API, and CalDAV/CardDAV protocols.

Requires: Nextcloud Notes app installed on the instance (for Notes features). All other features work with a standard Nextcloud installation.

Setup

Run the guided setup to configure credentials:

python3 ~/.hermes/skills/productivity/nextcloud/scripts/setup.py

The setup script will:

  1. Ask for your Nextcloud URL, username, and App Password
  2. Validate connectivity against your instance
  3. Save credentials to ~/.hermes/nextcloud.env

Alternatively, set environment variables manually:

export NEXTCLOUD_URL="https://your-nextcloud.example.com"
export NEXTCLOUD_USER="your_username"
export NEXTCLOUD_TOKEN="***"
export NEXTCLOUD_TIMEZONE="Europe/Prague"  # optional, defaults to UTC

Creating an App Password

  1. Log in to your Nextcloud instance
  2. Go to Settings → Security → App passwords
  3. Click Add new app password
  4. Enter a name (e.g. hermes-agent) and click Create
  5. Copy the generated password — it is shown only once

Verifying the Setup

NC="python3 ~/.hermes/skills/productivity/nextcloud/scripts/nextcloud_api.py"
$NC check

Expected output: {"status": "success", "data": {"authenticated": true, "user": "your_username"}}

Architecture

FeatureProtocolEndpoint
FilesWebDAV/remote.php/dav/files/<user>/
NotesREST API/index.php/apps/notes/api/v1/notes
TasksCalDAV (VTODO)/remote.php/dav/calendars/<user>/
Calendar EventsCalDAV (VEVENT)/remote.php/dav/calendars/<user>/
ContactsCardDAV/remote.php/dav/addressbooks/<user>/

Authentication: HTTP Basic Auth with App Password (user:token).

Usage

Define the convenience alias:

NC="python3 ~/.hermes/skills/productivity/nextcloud/scripts/nextcloud_api.py"

Files (WebDAV)

List directory contents

$NC files list --path "/Documents"
$NC files list  # root folder

Returns: {"status": "success", "data": [{"path": "...", "type": "file|dir", "size": N, "mtime": "ISO8601"}]}

Get file content

$NC files get --path "/Documents/notes.md"

Upload file

$NC files upload --path "/Documents/new-file.txt" --content "File content here"

Create directory

$NC files mkdir --path "/Documents/projects"

Delete file or directory

$NC files delete --path "/Documents/old-file.txt"

Warning: Deletion is permanent and recursive for directories.

Move / rename

$NC files move --src "/Documents/old-name.txt" --dst "/Documents/new-name.txt"

Search files

$NC files search --query "budget"

Notes (Nextcloud Notes API)

Requires the Notes app installed in Nextcloud.

List notes

$NC notes list
$NC notes list --category "work"

Get note by ID

$NC notes get --id 42

Create note

$NC notes create --title "Meeting Notes" --content "Discussion points..."
$NC notes create --title "Work Note" --content "..." --category "work"

Update note

$NC notes edit --id 42 --title "Updated Title" --content "New content"
$NC notes edit --id 42 --category "personal"

Delete note

$NC notes delete --id 42

Tasks (CalDAV VTODO)

List task lists (calendars)

$NC calendars list --type tasks

List tasks from a calendar

$NC tasks list
$NC tasks list --calendar "Personal"

Create task

$NC tasks create --title "Finish quarterly report" --due "2026-06-30T17:00:00Z" --priority 5
$NC tasks create --title "Call with client" --calendar "Work" --due "2026-06-15T10:00:00Z" --priority 3

Priority: 0 = none, 1 = highest, 9 = lowest.

Update task

$NC tasks edit --uid "abc123def" --title "New title" --priority 9
$NC tasks edit --uid "abc123def" --due "2026-07-01T12:00:00Z"

Mark task complete

$NC tasks complete --uid "abc123def"

Delete task

$NC tasks delete --uid "abc123def"

Calendar Events (CalDAV VEVENT)

List event calendars

$NC calendars list --type events

List events

$NC calendar list
$NC calendar list --from "2026-07-01T00:00:00Z" --to "2026-07-07T23:59:59Z"
$NC calendar list --calendar "Work"

Default range: next 7 days.

Create event

$NC calendar create --summary "Team Standup" --start "2026-07-01T09:00:00Z" --end "2026-07-01T09:30:00Z"
$NC calendar create --summary "Conference" --start "2026-09-15T08:00:00Z" --end "2026-09-17T18:00:00Z" --location "Prague" --calendar "Work"

Update event

$NC calendar edit --uid "xyz789" --summary "New Title"
$NC calendar edit --uid "xyz789" --start "2026-07-02T10:00:00Z" --end "2026-07-02T11:00:00Z"

Delete event

$NC calendar delete --uid "xyz789"

Contacts (CardDAV)

List address books

$NC addressbooks list

List contacts

$NC contacts list
$NC contacts list --addressbook "Personal"

Search contacts

$NC contacts search --query "John"

Get contact by UID

$NC contacts get --uid "contact-uid-string"

Create contact

$NC contacts create --name "John Doe" --email "john@example.com" --phone "+420123456789"
$NC contacts create --name "Jane Smith" --email "jane@example.com" --organization "Acme Corp" --title "Engineer"

Update contact

$NC contacts edit --uid "contact-uid-string" --phone "+420987654321" --email "newemail@example.com"

Delete contact

$NC contacts delete --uid "contact-uid-string"

Output Format

All commands return JSON:

{"status": "success", "data": {...}}
{"status": "error", "message": "Descriptive error message"}

For list operations, data is always an array even if empty: [].


Environment Variables

VariableRequiredDescription
NEXTCLOUD_URLYesBase URL of your Nextcloud instance (no trailing slash)
NEXTCLOUD_USERYesYour Nextcloud username
NEXTCLOUD_TOKENYesApp Password (from Settings → Security → App passwords)

Credentials are stored in ~/.hermes/nextcloud.env by the setup script. The skill reads them automatically if present.


Error Handling

HTTP CodeMeaningCommon Cause
401UnauthorizedInvalid or expired App Password
403ForbiddenUser lacks permission for this resource
404Not FoundWrong path, or Notes app not installed
409ConflictDestination already exists (on move/rename)
424Method Not AllowedFeature not supported by server (e.g. Notes API)

Rules for Hermes Agent

  1. Confirm before destructive operations — always show what will be deleted before running a delete command
  2. Use App Password, never primary password — App Password can be revoked without affecting primary credentials
  3. Respect rate limits — avoid rapid sequential API calls; batch reads where possible
  4. Verify Notes app availability — if Notes API returns 404, inform the user the Notes app may not be installed
  5. Handle missing credentials gracefully — if env vars are not set, prompt user to run setup.py

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.