How do I install the Noctalia skill?

Run npx skillmds@latest add tomevault-io/noctalia 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 Noctalia safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Noctalia?

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 Noctalia free to use?

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

Who published Noctalia?

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

Noctalia by tomevault-io — Agent Skill

Name: Noctalia
Author: tomevault-io

Noctalia

This skill should be used when the user asks to "configure noctalia", "change noctalia settings", "debug noctalia", "restart noctalia", or mentions noctalia shell, quickshell, or noctalia IPC. Provides common patterns for working with noctalia shell in this NixOS config. Use when this capability is needed.

tomevault-io 389a437 2 files · 3.6 KB Updated Sep 17, 2026

File contents

Noctalia Shell Configuration

This skill provides common patterns for configuring and debugging the noctalia desktop shell.

Configuration Location

home/desktop/shell/noctalia/default.nix

The nix config generates ~/.config/noctalia/settings.json (symlinked to nix store).

Key Concepts

Settings Format

Noctalia settings are JSON. The nix home-module accepts freeform attributes that get serialized to JSON. Key gotcha: nested objects must match noctalia's expected structure exactly.

Runtime State vs Config

settings.json - What nix generates (read-only symlink)
Runtime state - What noctalia is actually using (can differ if UI changes were made)
Always verify runtime state via IPC after changes

IPC Commands

Query and control noctalia via IPC:

# Get full runtime state
noctalia-shell ipc call state all

# List available IPC targets
noctalia-shell ipc show

# Common targets
noctalia-shell ipc call launcher toggle
noctalia-shell ipc call controlCenter toggle
noctalia-shell ipc call settings toggle
noctalia-shell ipc call wallpaper random

Debugging & Verification

Check runtime state

noctalia-shell ipc call state all | jq '.settings'

Check generated config

cat ~/.config/noctalia/settings.json | jq .

Restart noctalia (apply changes without logout)

systemctl --user restart noctalia-shell

VM workflow (rebuild + restart + verify)

./scripts/dev-sync rebuild && \
sshpass -p 'test' ssh altan@192.168.122.3 \
  'systemctl --user restart noctalia-shell && sleep 2 && noctalia-shell ipc call state all' | jq '.settings'

Common Issues

Changes not applying

Verify settings.json has correct content: cat ~/.config/noctalia/settings.json
Restart noctalia: systemctl --user restart noctalia-shell
Check runtime state matches: noctalia-shell ipc call state all | jq

Wrong JSON structure

Noctalia expects specific nested structures. Example for bar widgets:

Wrong: bar.widgetsLeft = [...]
Correct: bar.widgets.left = [...]

Widgets not appearing

All widgets must be objects with id field:

Wrong: "Clock"
Correct: { id = "Clock"; }

Related Skills

noctalia-bar - Bar widget layout and settings

External Resources

Docs: https://docs.noctalia.dev/
IPC docs: https://docs.noctalia.dev/development/plugins/ipc/
GitHub: https://github.com/noctalia-dev/noctalia-shell

Converted and distributed by TomeVault — claim your Tome and manage your conversions.

---name: noctaliadescription: This skill should be used when the user asks to "configure noctalia", "change noctalia settings", "debug noctalia", "restart noctalia", or mentions noctalia shell, quickshell, or noctalia IPC. Provides common patterns for working with noctalia shell in this NixOS config. Use when this capability is needed.---# Noctalia Shell ConfigurationThis skill provides common patterns for configuring and debugging the noctalia desktop shell.## Configuration Location```home/desktop/shell/noctalia/default.nix```The nix config generates `~/.config/noctalia/settings.json` (symlinked to nix store).## Key Concepts### Settings FormatNoctalia settings are JSON. The nix home-module accepts freeform attributes that get serialized to JSON. Key gotcha: nested objects must match noctalia's expected structure exactly.### Runtime State vs Config- **settings.json** - What nix generates (read-only symlink)- **Runtime state** - What noctalia is actually using (can differ if UI changes were made)- Always verify runtime state via IPC after changes## IPC CommandsQuery and control noctalia via IPC:```bash# Get full runtime statenoctalia-shell ipc call state all# List available IPC targetsnoctalia-shell ipc show# Common targetsnoctalia-shell ipc call launcher togglenoctalia-shell ipc call controlCenter togglenoctalia-shell ipc call settings togglenoctalia-shell ipc call wallpaper random```## Debugging & Verification### Check runtime state```bashnoctalia-shell ipc call state all | jq '.settings'```### Check generated config```bashcat ~/.config/noctalia/settings.json | jq .```### Restart noctalia (apply changes without logout)```bashsystemctl --user restart noctalia-shell```### VM workflow (rebuild + restart + verify)```bash./scripts/dev-sync rebuild && \sshpass -p 'test' ssh altan@192.168.122.3 \ 'systemctl --user restart noctalia-shell && sleep 2 && noctalia-shell ipc call state all' | jq '.settings'```## Common Issues### Changes not applying1. Verify settings.json has correct content: `cat ~/.config/noctalia/settings.json`2. Restart noctalia: `systemctl --user restart noctalia-shell`3. Check runtime state matches: `noctalia-shell ipc call state all | jq`### Wrong JSON structureNoctalia expects specific nested structures. Example for bar widgets:- **Wrong:** `bar.widgetsLeft = [...]`- **Correct:** `bar.widgets.left = [...]`### Widgets not appearingAll widgets must be objects with `id` field:- **Wrong:** `"Clock"`- **Correct:** `{ id = "Clock"; }`## Related Skills- **noctalia-bar** - Bar widget layout and settings## External Resources- Docs: https://docs.noctalia.dev/- IPC docs: https://docs.noctalia.dev/development/plugins/ipc/- GitHub: https://github.com/noctalia-dev/noctalia-shell---> Converted and distributed by [TomeVault](https://tomevault.io/claim/altans) — claim your Tome and manage your conversions.

Frequently asked questions