Skills for AI agents working with Nextcloud: setting up development environments, building Nextcloud apps in PHP and External Apps (ExApps) in any language, and operating or fixing them on real instances, development and production alike.
Three terms carry the whole repository: AppAPI is the Nextcloud component that runs ExApps (services living in their own containers next to Nextcloud), HaRP is AppAPI's recommended reverse-proxy deploy daemon, and occ is Nextcloud's admin console. The skills teach everything else.
The skills use the open Agent Skills format (a SKILL.md file with plain-markdown
instructions plus bundled references and assets), so they work with Claude Code and claude.ai, ChatGPT and
Codex, Gemini CLI, VS Code, and any other agent or human that can read files. Only the vendor-neutral
frontmatter fields are used.
| Skill | Use it to |
|---|---|
| nextcloud-dev-setup | Build a local Nextcloud development environment on nextcloud-docker-dev: Nextcloud from source, AppAPI, a HaRP deploy daemon, and a smoke-tested ExApp deploy |
| exapp-development | Write an ExApp in any language against the raw AppAPI contract, with a runnable framework-free reference app and two iteration loops |
| exapp-maintenance | Fix or extend an ExApp that is already installed: clone matching sources, patch, rebuild the image, redeploy in place without losing data |
| exapp-operations | Install and operate AppAPI and ExApps with occ on Docker, Kubernetes, remote hosts or AIO, and troubleshoot symptom-first |
| harp-operations | Run and debug HaRP itself: probes, configuration, log decoding, certificates, upgrades and load-related failures |
| nextcloud-ai-stack | Install, verify and debug Nextcloud's AI features: Assistant, Task Processing and the provider apps behind them, local or external |
| nextcloud-php-app | Build a Nextcloud PHP app from an empty directory to a release tarball: routes, templates, database, settings, a Vue frontend, PHPUnit and Psalm, packaging, and Playwright tests against a real instance |
Every runbook was executed end to end against a live environment before being written down, and carries a
"Last verified against" line naming the Nextcloud version and the tools it was checked with. The
load-bearing claims are also executable: tests/verify.py replays them against a live
instance, so a skill can be re-proven rather than re-read. The content is maintained alongside AppAPI and
updated as AppAPI evolves.
/plugin marketplace add oleksandr-nc/nextcloud-skills
/plugin install nextcloud-skills@nextcloud-skills
The skills then load automatically whenever a matching task comes up, and can be invoked directly by name.
Clone the repository and copy or symlink the skills you want into your skills directory:
git clone https://github.com/oleksandr-nc/nextcloud-skills
ln -s "$(pwd)/nextcloud-skills/skills/"* ~/.claude/skills/(Use a project's .claude/skills/ instead of ~/.claude/skills/ to scope them to one project.)
Clone the repository (or fetch single files raw from GitHub) and point your agent at
AGENTS.md, which routes to the right skill, or directly at the relevant
skills/<name>/SKILL.md. The files are self-contained markdown; no runtime or tooling is required to follow
them. Tools that support the Agent Skills format natively can install the skills/<name> directories in
their usual way.
Several skills verify user interfaces. An agent without a browser can only fetch HTML, which cannot show
whether a script ran, whether the Content Security Policy blocked it, or what a component actually rendered.
An MCP browser server (chrome-devtools-mcp, or @playwright/mcp) fixes that, and its accessibility
snapshots hand you the roles and accessible names that test locators need. Setup, verified:
dev-environment.md, Stage 8.
skills/<name>/SKILL.md the entry point: when to use, how to work, the critical facts
skills/<name>/references/ the full runbooks the skill executes from
skills/<name>/assets/ runnable material (reference app, diagnostic scripts)
tests/verify.py replays each skill's load-bearing claims against a live instance
scripts/validate_skills.py structure, links, anchors and the verified-against promise
SKILL.md is deliberately short; agents read the referenced runbooks when they actually execute the task
(progressive disclosure). The runbooks are written stage by stage with Verify blocks and symptom-first
troubleshooting tables, so an agent can execute them unaided and a human can follow along.
Planned additions, in no particular order: an nc_py_api (Python ExApp) quickstart, Task Processing (AI provider) development, Talk bots, ExApp UI integration, and backup, restore and daemon migration. Suggestions and contributions are welcome through issues and pull requests.
This repository is the canonical home of the AppAPI guides: the
nextcloud/app_api repository's AGENTS.md points here.
Maintained by the Nextcloud AppAPI maintainers; the repository is planned to move under the Nextcloud GitHub organization (GitHub redirects will keep existing links working). Questions and documentation problems: GitHub issues, answered on a best-effort basis. Security reports: see SECURITY.md.
See CONTRIBUTING.md for the skill format, authoring rules and validation. Every commit
needs a DCO sign-off (git commit -s).
AGPL-3.0-or-later. This repository is REUSE-compliant.