AI Agent Skills#
Luma includes four skills for AI coding assistants. They cover deployment, observability, log investigation, remote commands and interactive terminals. They are installed in the assistant, not in the running cluster.
Deployment workflows#
luma-deployment-yaml helps generate and review single-service manifests and Compose sidecars, choose region and exposure, enable and audit CDN caching, configure local storage, and troubleshoot builds or deployments.
For an existing application, it follows the recorded build and deployment workflow. A change of workflow must be explained and confirmed; a skill installation alone does not update the CLI or Control. Secrets remain references such as ${DATABASE_PASSWORD}, not plaintext in YAML.
Example request:
Review this Compose project, generate its Luma sidecar, and validate it. Keep the existing deployment workflow and use local persistent storage.
Application observability#
luma-observe helps deploy and operate the optional, independent observability stack: Traefik request metrics, Nomad allocation failures, OTLP collection and notification delivery.
The skill distinguishes observe's vmalert/Alertmanager rules from Control's dashboard-managed application alert presets, and covers authenticated Grafana access, telemetry retention and notification setup.
Installing the skill does not install the stack. The stack requires its own deployment; application tracing also requires the appropriate OpenTelemetry runtime instrumentation.
Example request:
Set up luma-observe for this cluster, verify application metrics and failed-allocation alerts, and check notification delivery.
Log investigation#
luma-logs uses luma app alerts, luma app log-query,
runtime events and deployment history to investigate application failures. It
queries authenticated Control APIs, without exposing storage ports or extracting
credentials. See the log query API.
Example request:
Analyze this application's errors over the last hour, distinguish retries from final task failures, and explain the impact with log evidence.
Interactive terminals#
luma-shell covers non-TTY luma node exec NODE -- COMMAND... for agents and scripts (stdin, separate stdout/stderr, exit status and cancellation), plus luma node shell NODE and
luma app shell FULL_SERVICE_NAME, including PTY interaction, direct TLS and
Control relay without SSH. It explains why closed inbound ports require relay,
how to read actual socket addresses and Control RTT, and which components need upgrading. Clients need no Tailscale membership; exec defaults to relay. See
local terminals for configuration and usage.
Example request:
Connect to this Luma node from my terminal without SSH. Prefer direct transport, but use Control relay if the node's inbound ports are closed.
Installation and automatic updates#
Install the suite bundled with the currently installed CLI:
luma skills install --agent codex
luma skills install --agent claude
# Other assistants, with a remembered custom destination:
luma skills install --path /absolute/path/to/assistant/skills
luma skills status --format json
luma update and the installer refresh existing suites from the same release.
For pip/uv upgrades, the next ordinary Luma command also synchronizes the packaged
skills. No skills are downloaded from a separate main branch. Existing manual
copies in Codex/Claude directories are adopted, and newly added Luma skills join
that suite. Assistants with no existing Luma suite are left alone until install.
CODEX_HOME, CLAUDE_CONFIG_DIR and registered custom paths are supported. A
privileged installer updates the target user's default directories as that user;
non-default assistant paths should first be registered with skills install.
Each skill records the paired version and content hashes in .luma-managed.json.
On upgrades, changed local files are backed up to luma-skill-backups beside the
assistant's skills directory before replacement. The backup path is printed.
Unchanged managed files are replaced without accumulating backups; obsolete files
inside a skill disappear with the directory replacement. A symlinked skill is
left untouched with an explicit warning. Permission failures do not fail the CLI
upgrade, but are reported as incomplete synchronization. Resolve them and run:
luma skills sync
# Restore the bundled content even after editing an already-current version:
luma skills sync --force
status is read-only and reports pairing and local modifications. Same-release
local edits are left in place until a new bundle arrives or --force is used.
Keep reusable custom instructions separately or reapply them from the backup.
Source checkouts do not auto-sync on ordinary command execution; use skills sync
explicitly while developing. All skill references are included in wheel and source
packages. Installing a skill does not upgrade Control or deploy luma-observe.
Reload the skill or start a new assistant conversation after an update.
Observation CLI delivery#
luma observe status/app/alerts/tasks, luma-observe and luma-logs ship together
in luma-infra. Other users upgrade through their existing pip, pipx, uv tool or
Luma installation workflow. Existing assistant suites synchronize from that
package; no files from a developer's computer are required. First-time users run
skills install above, using --path to register another assistant's directory.
luma version --local
luma observe --help
luma skills status --format json
luma observe status --format json
luma observe app APP --since 1h --format json
luma observe alerts --app APP --format json
luma observe tasks APP --view events --outcome problem --since 1h --format json
CLI and skill upgrades change the client only. Shared queries require an updated Control; self-monitoring, structured logs and durable queues require updated Observe; resource identity completion requires updated node agents. Check the CLI version for missing commands, Control for missing endpoints, and collection for missing samples. Skills do not perform these cluster upgrades automatically.
Source CI and the PyPI release job verify the final wheel and source distribution contain every canonical skill file, then install the wheel outside the checkout to verify commands, Codex/Claude/custom installations, automatic upgrade sync and local-edit backups. Failure blocks distribution upload in that release job.