Skip to content

arch3rPro/1Panel-Appstore / skills

1panel-app-builder

Verified

Use when packaging Docker deployments as 1Panel local app store apps, including GitHub projects, docker-compose.yml files, docker run commands, app metadata, version directories, icons, README files, and 1Panel validation.

FileKindSize
README.mdmarkdown2.6 KB
SKILL.mdskill md5.1 KB
evals/evals.jsonconfig1.6 KB
examples/example-usage.mdmarkdown2.3 KB
references/1panel-examples.mdmarkdown9.1 KB
scripts/download-icon.shexecutablescript7.6 KB
scripts/generate-app.shexecutablescript27.0 KB
scripts/validate-app.shexecutablescript11.6 KB
templates/data.yml.tplother1.1 KB
templates/docker-compose.yml.tplother396 B
tests/run_all.shexecutablescript358 B
tests/test_skills_scripts.shexecutablescript13.4 KB
---
name: 1panel-app-builder
description: Use when packaging Docker deployments as 1Panel local app store apps, including GitHub projects, docker-compose.yml files, docker run commands, app metadata, version directories, icons, README files, and 1Panel validation.
---

# 1Panel App Builder

Build or review 1Panel local app store packages from Docker deployments.

## When To Use

Use this skill when the user asks to:

- Add or package a 1Panel local app store app.
- Convert a GitHub project, `docker-compose.yml`, or `docker run` command into `apps/<app-key>/`.
- Fix 1Panel app metadata, port variables, compose files, README files, icons, or version directories.
- Validate an app package before commit.

For detailed real app examples, read `references/1panel-examples.md` only when needed.

## Required Shape

```text
apps/<app-key>/
├── data.yml
├── logo.png
├── README.md
├── README_en.md
└── <version>/
    ├── data.yml
    ├── docker-compose.yml
    └── data/
```

Some apps also include `latest/`. When both `latest/` and a concrete version exist, `latest/` must use image tag `latest`, and the concrete version directory should use the pinned tag.

## Workflow

1. Inspect the source deployment.
   - GitHub: inspect README/deploy docs and registry image; the generator checks common compose paths before README `docker run` fallback.
   - Compose: parse services, image tags, ports, volumes, environment, dependencies.
   - Docker run: parse image, `--name`, `-p/--publish`, `-v/--volume`, `-e/--env`, and `--env-file`.
2. Choose a stable app key.
   - Lowercase, hyphenated, directory-safe.
   - `additionalProperties.key` must match the directory name.
3. Generate or edit app files.
   - Prefer `latest/` plus a concrete version when a concrete image tag is known.
   - Preserve source volumes and environment unless they conflict with 1Panel conventions.
4. Resolve a real icon.
   - Do not create placeholders.
   - Use `--icon-mode skip` for drafts, `cache-only` for offline work, and `required` when an icon is mandatory.
5. Validate before delivery.
   - Run `skills/scripts/validate-app.sh ./apps/<app-key>`.
   - For Skill script changes, run `skills/tests/run_all.sh`.

## 1Panel Rules

- `container_name` should be `${CONTAINER_NAME}`.
- Services should use `restart: always`.
- Use external `1panel-network`.
- Port mappings should use `PANEL_APP_PORT_*` variables defined in the version `data.yml`.
- Persistent mounts should prefer relative `./data/...` paths.
- Add `labels: createdBy: "Apps"`.
- Keep metadata tags aligned with top-level `data.yaml`.

Preferred port variables:

```text
PANEL_APP_PORT_HTTP
PANEL_APP_PORT_HTTPS
PANEL_APP_PORT_API
PANEL_APP_PORT_ADMIN
PANEL_APP_PORT_PROXY
PANEL_APP_PORT_PROXY_HTTP
PANEL_APP_PORT_PROXY_HTTPS
PANEL_APP_PORT_DB
PANEL_APP_PORT_SSH
PANEL_APP_PORT_S3
PANEL_APP_PORT_SYNC
```

## Scripts

Run from `/root/github/1Panel-Appstore/skills` unless noted.

Generate a draft:

```bash
./scripts/generate-app.sh --app-key my-app --name MyApp --version 1.2.3 --icon-mode skip ./docker-compose.yml
```

Useful generation options:

```text
--output <dir>       Output base directory. Default: ./apps
--app-key <key>      Override app directory key.
--name <name>        Override display name.
--service <name>     Select the main service from a multi-service compose file.
--version <tag>      Override concrete version and image tag.
--icon-mode <mode>   auto|required|skip|cache-only
--icon-url <url>     Download icon from a known URL.
--force              Allow overwriting an existing generated directory.
--dry-run            Print parsed values without writing files.
--check-deps         Check required local tools.
```

Download an icon:

```bash
./scripts/download-icon.sh --mode cache-only redis ./logo.png
./scripts/download-icon.sh --mode required --url https://example.com/logo.png myapp ./logo.png
```

Validate an app:

```bash
./scripts/validate-app.sh ../apps/<app-key>
```

Validate Skill tooling:

```bash
./tests/run_all.sh
```

## Icon Policy

Icon lookup order:

1. Known explicit URL (`--icon-url`).
2. Local cache under `skills/.cache/icons`.
3. Dashboard Icons.
4. Simple Icons.
5. selfh.st Icons.

Missing icons are acceptable for drafts only. For final app delivery, leave `logo.png` absent and tell the user what is missing instead of inventing an inaccurate image.

## Validation Gate

Before considering an app ready:

- Run `./scripts/validate-app.sh ../apps/<app-key>`.
- Confirm `latest/` uses `:latest`.
- Confirm concrete version directories use matching image tags or document the exception.
- Confirm every compose `PANEL_APP_PORT_*` variable exists in the version `data.yml`.
- Inspect generated README and metadata manually; the generator is a starting point, not an authority.

## Common Mistakes

- Keeping a placeholder `logo.png`.
- Using a host absolute volume path when `./data/...` would work.
- Forgetting to define a port variable used by `docker-compose.yml`.
- Letting `additionalProperties.key` drift from the app directory name.
- Treating generated metadata, descriptions, tags, and architectures as final without review.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall