aroldobossoni/community-scripts-agent-skill / skills/community-scripts-rules
community-scripts-rules
UnverifiedGuides AI agents working on Community Scripts / Proxmox VE Helper Scripts contributions. Use when creating, updating, testing, or opening PRs for community-scripts/ProxmoxVED or community-scripts/ProxmoxVE, or when the user mentions Community Scripts, ProxmoxVED, ProxmoxVE helper scripts, ct scripts, install scripts, json metadata, dev_mode, or the official PR template.
Community Scripts Rules
Use this skill before changing, testing, or submitting Community Scripts work.
Official Sources
Always verify current rules from official sources before coding or opening a PR:
https://community-scripts.org/docshttps://community-scripts.org/docs/contributionhttps://community-scripts.org/docs/dev_modehttps://github.com/community-scripts/ProxmoxVEDhttps://github.com/community-scripts/ProxmoxVED/blob/main/.github/pull_request_template.mdhttps://github.com/community-scripts/ProxmoxVED/blob/main/AGENTS.mdhttps://github.com/community-scripts/ProxmoxVED/blob/main/.github/agents/pve-script-creator.agent.mdhttps://github.com/community-scripts/ProxmoxVE/blob/main/CONTRIBUTING.md
Prefer raw GitHub URLs when fetching markdown:
https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/.github/pull_request_template.mdhttps://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/AGENTS.mdhttps://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/.github/agents/pve-script-creator.agent.mdhttps://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/CONTRIBUTING.md
If official sources conflict, use ProxmoxVED rules for new scripts and ProxmoxVE rules for fixes to existing promoted scripts.
Repository Routing
- New scripts go to
community-scripts/ProxmoxVED. - Existing script fixes, improvements, and features go to
community-scripts/ProxmoxVE. - Do not open new-script PRs directly against
ProxmoxVE; they are closed without review. - Keep PRs small and focused.
Mandatory ProxmoxVED Rules
For new ProxmoxVED application scripts:
- Create exactly three files:
ct/<app>.sh,install/<app>-install.sh, andjson/<app>.json. - CT scripts source
misc/build.func(orbuild.func). - Install scripts source
$FUNCTIONS_FILE_PATH. - CT scripts declare all required
var_*values, includingvar_arm64. - CT scripts implement
update_script(). - CT scripts end with
start,build_container,description, and the standard access footer. - Install scripts call
color,verb_ip6,catch_errors,setting_up_container,network_check, andupdate_os. - Install scripts end with
motd_ssh,customize, andcleanup_lxc. - Prefer bare-metal installation; never use Docker for installation scripts.
- Use helper functions instead of custom implementations.
Required Helpers
Always use project helpers instead of custom implementations:
Source Deploy & Release Fetchers
fetch_and_deploy_gh_release "<app>" "owner/repo" "<mode>" ["latest"] ["/opt/<app>"] ["<asset-pattern>"]- GitHub releases. Modes:
tarball(source),binary(.deb),prebuild(prebuilt archive),singlefile(single binary). - The resolved version is written to
~/.<app>(read back withcat ~/.<app>when needed at build/runtime).
- GitHub releases. Modes:
fetch_and_deploy_gl_release/fetch_and_deploy_gl_tag- GitLab (self-hosted or gitlab.com).
- Set
GITLAB_URL="https://gitlab.example.org"(defaulthttps://gitlab.com) and optionalGITLAB_TOKEN. - Same modes as GitHub helper. Do not use GitHub helper for GitLab repositories.
fetch_and_deploy_codeberg_release- Codeberg releases.
fetch_and_deploy_from_url- Fallback for fixed URLs when no release API fits (avoids hand-rolled curl/tar).
- Multi-arch asset resolution:
- Build asset patterns with
arch_resolve "x86_64" "arm64"instead of hardcoding architecture strings.
- Build asset patterns with
Update Checks
check_for_gh_release "<app>" "owner/repo"(returns 0 when newer release exists).check_for_gl_release(withGITLAB_URL).get_latest_github_release "owner/repo"(returns latest release version string).
Runtimes
NODE_VERSION="22" NODE_MODULE="pnpm@x" setup_nodejssetup_go(no argument = latest; never pin a bare1.23— requires full1.23.x)RUST_CRATES="..." setup_rustUV_PYTHON="3.12" setup_uvRUBY_VERSION setup_rubyJAVA_VERSION setup_javaPHP_VERSION="8.3" PHP_MODULE="gd,intl,mysql" PHP_FPM="YES" setup_php(note singularPHP_MODULE)
Databases
setup_postgresql+PG_DB_NAME PG_DB_USER PG_DB_EXTENSIONS="vector,pg_stat_statements" [PG_DB_GRANT_SUPERUSER="true"] setup_postgresql_db- List every extension enabled by app schema. Non-trusted extensions need pre-creating. Grant superuser only if strictly needed.
setup_mariadb+setup_mariadb_dbsetup_mysql+setup_mysql_dbsetup_mongodbsetup_clickhousesetup_meilisearch
Tools & Infrastructure
setup_composersetup_ffmpegsetup_imagemagicksetup_gssetup_yqsetup_adminersetup_hwaccelsetup_nltk
Repositories, Services, Dependencies & TLS
setup_deb822_repo "name" "<gpg_url>" "<repo_url>" "<suite>" ["component"] ["archs"]for 3rd-party APT repositories (never hand-roll GPG keys or sources.list files).safe_service_restart <svc>ensure_dependencies <pkg...>(installs jq, openssl, etc. on demand).install_packages_with_retry <pkg...>create_self_signed_cert "<app>"->/etc/ssl/<app>/<app>.{crt,key}(SAN covers hostname + container IP + localhost; never hand-roll openssl).
Data Persistence & Updates (Critical)
CLEAN_INSTALL=1 fetch_and_deploy_* wipes /opt/<app> before re-extracting. Any user state or secrets stored inside /opt/<app> will be permanently lost during updates.
Follow these strict rules:
-
Standard Pattern (Preferred):
- Store all persistent state and data outside the app directory in
/opt/<app>_data(NOT/opt/<app>/data). - Point the application there via its data directory configuration or environment variables (e.g.
DATA_DIR,*_DATA_DIR). - Place non-regenerable configuration and secrets (signing keys, generated
.env,.toml) in/opt/<app>_dataas well. - Updates keep everything with no backup or restore step required.
- Store all persistent state and data outside the app directory in
-
Exception Pattern (Manifest Backup Helpers):
- Only when data genuinely cannot be relocated outside
/opt/<app>, back it up inupdate_script()using the manifest helpers (never use manualcpor/tmp):create_backup /opt/<app>/data /opt/<app>/.env CLEAN_INSTALL=1 fetch_and_deploy_gh_release ... restore_backup create_backupcopies paths into/opt/<NSAPP>.backupwith a manifest, is idempotent, and aborts update on failure.restore_backuprestores every manifest path and removes the backup store.- Override default backup store location with
BACKUP_DIRif/opt/<NSAPP>.backupclashes.
- Only when data genuinely cannot be relocated outside
-
Never back up to
/tmp(temporary directories can be cleared by the system).
Secure-Context Web Apps (HTTPS)
Modern browser APIs such as crypto.subtle (Web Crypto / PKCE), navigator.storage.getDirectory (OPFS), service workers, and SharedArrayBuffer require a secure context (HTTPS or localhost). Applications using them break over plain http://<IP> with errors like crypto.subtle is unavailable in insecure contexts.
When an application requires a secure context:
- Terminate TLS with
create_self_signed_cert "<app>"behind an Nginx reverse proxy listening on port 443 with SSL enabled. - Redirect port 80 to port 443.
- Proxy requests to the application on its internal port (or serve static files directly).
- If the application source uses
SharedArrayBuffer, configure cross-origin isolation headers on the HTTPS server:add_header Cross-Origin-Opener-Policy same-origin always;add_header Cross-Origin-Embedder-Policy require-corp always;
- In
json/<app>.jsonnotes, instruct users to accept the self-signed certificate in their browser and access the application viahttps://.
Anti-Patterns
Never do these unless official rules explicitly change:
- Do not wrap
setup_*,fetch_and_deploy_*, orcheck_for_*inmsg_info/msg_okblocks (they have built-in logging). - Do not use Docker for ProxmoxVED install scripts.
- Do not implement custom download logic when a helper exists.
- Do not implement custom version checks when
check_for_*helpers apply. - Do not create pointless variables such as
APP_DIR,APP_USER, orAPP_PORT. - Do not use
sudo. - Do not use
apt-get; useapt. - Do not list pre-installed core packages as dependencies:
curl,sudo,wget,gnupg,ca-certificates,jq,mc. - Do not hardcode credentials, secrets, or versions for external tools.
- Do not back up to
/tmp; use/opt. - Do not use
echo,printf, orteefor file creation; use heredocs. - Do not create external shell scripts, custom credentials files, or unnecessary system users.
- Do not use
exportin.envfiles. - Do not add
systemctl daemon-reloadfor new services unless current rules require it. - Do not add
(Patience)in message labels. - Prefix package (
apt),npm, and build commands with$STD.
JSON Metadata
For json/<app>.json, include all required fields:
- Required fields:
name,slug,categories,date_created,type,updateable,privileged,architectures,interface_portdocumentation,website,repository,logo,descriptioninstall_methods,default_credentials,notes
- Optional fields:
platforms,app_vars
Metadata Rules
- No top-level
config_path:config_pathbelongs under individual install methods ininstall_methods(a script can have multiple methods with different paths). date_created: Today's date inYYYY-MM-DDformat.install_methods.resources: Must match CT script variables (var_cpu,var_ram,var_disk,var_os,var_version).repository: Upstream repository as a full URL (e.g.,https://github.com/owner/repo,https://gitlab.com/owner/repo,https://codeberg.org/owner/repo). Never bareowner/repo.logo: Use CDN pattern:https://cdn.jsdelivr.net/gh/selfhst/icons@main/webp/<slug>.webp.architectures: Replaced the deprecatedhas_armboolean. It must matchvar_arm64in the CT script (arch_checkaborts with exit code 106 on arm64 hosts when CT script saysno):
var_arm64 | architectures |
|---|---|
yes | ["amd64", "arm64"] |
no | ["amd64"] |
| unset | omit field |
platforms(optional):["pve"],["incus"]or both. Defaults to Proxmox VE if omitted. Only claimincusif script exists in the Incus repository.app_vars(optional): Declares variables for unattended installs. Requires matching 3-part implementation:install/<app>-install.sh(prompts only when unset):if [[ -z "${var_admin_user:-}" ]]; then read -rp "${TAB3}Admin username: " var_admin_user fi var_admin_user="${var_admin_user:-admin}"ct/<app>.sh(exports variable to container environment):export var_admin_user="${var_admin_user:-}"json/<app>.json(declares parameter metadata):"app_vars": [ { "name": "var_admin_user", "label": "Admin Username", "type": "text", "default": "admin" }, { "name": "var_admin_token", "label": "API Token", "type": "password", "secret": true, "required": true, "help": "The script exits when this is empty" } ]
- Supported
typevalues:text,password,number,boolean(emitsyes/no),select(withoptions). - Mark credentials and sensitive fields with
"secret": true.
Testing
Test on a real Proxmox host before PR when possible.
Useful development modes:
export dev_mode="keep,logs"
export var_verbose="yes"
bash -c "$(curl -fsSL https://raw.githubusercontent.com/<fork>/<repo>/<branch>/ct/<app>.sh)"
Use:
logsfor persistent logs under/var/log/community-scripts/.keepto preserve failed containers.motdfor early SSH access.pausefor step-by-step inspection.breakpointfor an interactive shell on failure.traceonly in isolated environments because it can expose secrets.dryrunfor simulation only.
Validate install, update path, service health, logs, credentials handling, exposed ports, and absence of hardcoded secrets.
PR Template Rules
Use the official ProxmoxVED PR template verbatim. Do not replace it with a custom body.
For new scripts, the PR must include:
🆕 New scriptchecked.- One arm64 option checked.
- All prerequisites checked only if true.
- Code and security review checkboxes checked only after self-review.
- Exactly one AI assistance option checked:
No AI used, orAI was used.
- All Application Requirements checked only if true:
- application is at least 6 months old;
- actively maintained;
- 600+ GitHub stars;
- official release tarballs are published;
- contributor understands not all scripts are accepted.
- Source links filled.
The automated check closes PRs missing required template sections or required checkbox selections.
Work Sequence
- Fetch current official rules from the sources above.
- Decide the correct repo:
ProxmoxVEDfor new scripts,ProxmoxVEfor existing promoted scripts. - Inspect similar existing scripts before coding.
- Implement with official helpers and standard structure (CT, install, JSON).
- Test with
dev_mode="keep,logs"and real Proxmox evidence. - Run the local checklist from this skill.
- Open PR only after checks pass.
- If the bot closes the PR, read the bot comment exactly and fix the missing rule before opening a replacement PR.
Local Checklist
- Official sources checked this session.
- Correct target repository selected (
ProxmoxVEDfor new,ProxmoxVEfor fixes/updates). - Exactly three files created:
ct/<slug>.sh,install/<slug>-install.sh,json/<slug>.json. - Script structure matches current templates (CT declarations, install flow, footers).
- Required helper functions used (fetch and deploy, runtimes, databases, tools).
- No wrapper
msg_*calls around helpers with built-in logging. - No anti-patterns present (no Docker, no
sudo, noapt-get,$STDprefix on apt/build). - Persistent data and configuration reside in
/opt/<app>_data(or managed viacreate_backup/restore_backupmanifest helpers). - Backups go to
/opt, never/tmp. - Multi-arch asset patterns use
arch_resolve(no hardcoded architecture tokens). - 3rd-party APT repos use
setup_deb822_repo; TLS certs usecreate_self_signed_cert. - GitLab sources use
fetch_and_deploy_gl_release/check_for_gl_releasewithGITLAB_URL. - Secure-context web applications configured with HTTPS reverse proxy (and COOP/COEP headers if using
SharedArrayBuffer). - CT
var_arm64accurately reflects arm64 support. - JSON metadata present and consistent with CT script resources.
- JSON
architecturesagrees with CTvar_arm64(yes->["amd64", "arm64"],no->["amd64"], unset -> omitted). - JSON
repositoryis a full URL (https://...), not bareowner/repo. - No top-level
config_pathin JSON (configured on install methods). - JSON
platformsclaimsincusonly if script exists in the Incus repository. - Every
readin install script is guarded by-z "${var_x:-}", exported inct/<app>.sh, and declared in JSONapp_vars. - Real install test completed or limitation documented.
-
update_script()reviewed or tested. - PR body uses official template verbatim.
- AI assistance checkbox is selected when AI was used.
- Bot comment reviewed if PR was closed.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |