How do I install the Umbrel App skill?

Run npx skillmds add zot24/umbrel-app in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Umbrel App safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: makes network calls. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Umbrel App?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Umbrel App free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Umbrel App?

zot24 (@zot24) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Umbrel App by zot24 — Agent Skill

Name: Umbrel App
Rating: 4.2 (5 reviews)
Author: zot24

Umbrel App

Expert Umbrel app developer. Use when the user wants to create, package, validate, test, debug, or submit apps for umbrelOS. Triggers on mentions of Umbrel apps, umbrelOS, app packaging, or Docker-to-Umbrel conversion.

zot24 b2fa2d8 14 files · 66.4 KB Updated Sep 10, 2026

File contents

Umbrel App Development Skill

Expert at developing, packaging, testing, and submitting apps for umbrelOS.

Overview

Scaffold - Create new apps from scratch with proper structure
Validate - Check apps for 20+ common issues
Convert - Transform Docker Compose apps to Umbrel format
PR Generation - Create submission-ready PR content
Debug - Troubleshoot installation and runtime issues

Quick Start

<app-id>/
├── docker-compose.yml    # Must include app_proxy service
├── umbrel-app.yml        # App manifest with metadata
└── exports.sh            # Environment exports (can be empty)

Critical Requirements

Image format: image: repo/name:tag@sha256:digest
Categories: files, finance, media, networking, social, automation, developer, gaming
Key variables: ${APP_DATA_DIR}, $APP_PASSWORD, $APP_BITCOIN_*, $APP_LIGHTNING_*

Documentation

For detailed information, see the reference documentation:

Scaffolding - Templates and directory structure
Validation - 20+ item checklist
Conversion - Docker-to-Umbrel mapping
Submission - PR template and assets
Community Stores - Custom app stores
Debugging - Common issues and fixes
Testing - Local and device testing
CLI Reference - Umbrel commands
Agent Operations - AI agent workflows
Security - Authentication and protection

Common Workflows

Create New App

Gather: name, ID, category, Docker image, port
Generate docker-compose.yml with app_proxy
Generate umbrel-app.yml manifest
Validate with checklist

Debug App Issue

SSH to umbrel@umbrel.local
Check logs: umbreld client apps.logs --appId <id>
Verify containers: docker ps
Check common issues in debugging.md

Submit to Official Store

Create PR at https://github.com/getumbrel/umbrel-apps
Include 256x256 SVG icon
Include 3-5 gallery images (1440x900 PNG)
Follow template in submission.md

Upstream Sources

Repository: https://github.com/getumbrel/umbrel-apps
Documentation: https://github.com/getumbrel/umbrel-apps/blob/master/README.md
Community Store Template: https://github.com/getumbrel/umbrel-community-app-store

Sync & Update

When user runs sync: fetch latest from upstream, update docs/ files. When user runs diff: compare current vs upstream, report changes.

---name: umbrel-appdescription: Expert Umbrel app developer. Use when the user wants to create, package, validate, test, debug, or submit apps for umbrelOS. Triggers on mentions of Umbrel apps, umbrelOS, app packaging, or Docker-to-Umbrel conversion.---# Umbrel App Development SkillExpert at developing, packaging, testing, and submitting apps for umbrelOS.## Overview- **Scaffold** - Create new apps from scratch with proper structure- **Validate** - Check apps for 20+ common issues- **Convert** - Transform Docker Compose apps to Umbrel format- **PR Generation** - Create submission-ready PR content- **Debug** - Troubleshoot installation and runtime issues## Quick Start```<app-id>/├── docker-compose.yml # Must include app_proxy service├── umbrel-app.yml # App manifest with metadata└── exports.sh # Environment exports (can be empty)```### Critical Requirements- Image format: `image: repo/name:tag@sha256:digest`- Categories: `files`, `finance`, `media`, `networking`, `social`, `automation`, `developer`, `gaming`- Key variables: `${APP_DATA_DIR}`, `$APP_PASSWORD`, `$APP_BITCOIN_*`, `$APP_LIGHTNING_*`## DocumentationFor detailed information, see the reference documentation:- **[Scaffolding](docs/scaffolding.md)** - Templates and directory structure- **[Validation](docs/validation.md)** - 20+ item checklist- **[Conversion](docs/conversion.md)** - Docker-to-Umbrel mapping- **[Submission](docs/submission.md)** - PR template and assets- **[Community Stores](docs/community-stores.md)** - Custom app stores- **[Debugging](docs/debugging.md)** - Common issues and fixes- **[Testing](docs/testing.md)** - Local and device testing- **[CLI Reference](docs/cli-reference.md)** - Umbrel commands- **[Agent Operations](docs/agent-operations.md)** - AI agent workflows- **[Security](docs/security.md)** - Authentication and protection## Common Workflows### Create New App1. Gather: name, ID, category, Docker image, port2. Generate docker-compose.yml with app_proxy3. Generate umbrel-app.yml manifest4. Validate with checklist### Debug App Issue1. SSH to `umbrel@umbrel.local`2. Check logs: `umbreld client apps.logs --appId <id>`3. Verify containers: `docker ps`4. Check common issues in [debugging.md](docs/debugging.md)### Submit to Official Store1. Create PR at https://github.com/getumbrel/umbrel-apps2. Include 256x256 SVG icon3. Include 3-5 gallery images (1440x900 PNG)4. Follow template in [submission.md](docs/submission.md)## Upstream Sources- **Repository**: https://github.com/getumbrel/umbrel-apps- **Documentation**: https://github.com/getumbrel/umbrel-apps/blob/master/README.md- **Community Store Template**: https://github.com/getumbrel/umbrel-community-app-store## Sync & UpdateWhen user runs `sync`: fetch latest from upstream, update docs/ files.When user runs `diff`: compare current vs upstream, report changes.

Frequently asked questions