A collection of agent skills for safe NethServer administration and development. Development guidance is derived from the NethServer Development Handbook. The same skill definitions can be installed in Claude Code, Codex, and Pi.

Skill definitions live under the skills/ directory.

Once installed, select a skill using your agent's invocation syntax, or let the agent pick it automatically:

• nethserver-admin — inspect, install, configure, and troubleshoot NS8 nodes over shell/SSH
• nethvoice-admin — diagnose, repair, and operate production NethVoice and NethVoice Proxy instances safely
• nethserver-containerfile — write and review secure, production-ready Containerfiles
• nethserver-issue — write well-structured GitHub issues
• nethserver-ns8-core — navigate and modify the ns8-core platform repository itself
• nethserver-ns8-module — develop and review NS8 modules (backend + frontend conventions)
• nethserver-pr — create and manage pull requests
• nethserver-release — create module and package releases following semver
• nethvoice-release — release a NethVoice milestone: ns8-nethvoice, ns8-nethvoice-proxy and NethLink, issue closing and testing cleanup
• conventional-commit — conventional commit messages with intelligent staging

The frontend-skills plugin, under plugins/frontend-skills/, holds the skills for the user interfaces that follow the Nethesis design systems: the Nebula Design System and, for NethServer 8, the Carbon Design System. It is a separate plugin, so you can install it without the NethServer skills:

• nebula-frontend — write and review frontends: Vue 3 projects built with Tailwind CSS and @nethesis/vue-components fully; text, icons, colors, typography and accessibility for other stacks; only text for NethServer 8 modules built with Carbon

To test a change to these skills, run their eval suite.

Agents initially load each skill's name and description, while its SKILL.md body is loaded only when the skill is invoked. Both cost context, so skills here follow two rules:

• Descriptions state triggers only. They say when to use the skill, not what it does or how it works. No feature lists — those belong in the body.
• Large skills use progressive disclosure. SKILL.md stays a short router: scope, the non-negotiable rules, and a reference map. The detail lives in references/*.md, and the agent reads only the one file its task needs.

skills/nethserver-ns8-module/
  SKILL.md                              # router: overview, always-applies rules, reference map
  references/layout-and-authorization.md
  references/backend.md
  references/backup-restore.md
  references/frontend.md

When adding to a split skill, put the content in the matching references/ file and add a keyword to its row in the reference map. Only add to SKILL.md if the rule applies no matter which reference file gets read. Three corollaries:

• A rule lives in one place only, either the router or a reference, never both. Duplicated rules drift apart.
• A rule kept in the router must not depend on a section that lives in a reference file, or an agent reading another reference gets the rule without its content.
• Reference paths are relative to the skill directory, so references/backend.md means skills/<skill>/references/backend.md.

Checks that are the same every time go in a scripts/ file that the skill runs, instead of commands in a reference: the agent spends one call on them, and every run checks the same things (see plugins/frontend-skills/skills/nebula-frontend/scripts/review-checks.sh).

Template-driven skills declare a cheaper model in frontmatter so they do not spend a frontier-model turn on mechanical work:

In Claude Code, the override applies to the turn that invokes the skill and is not saved to your settings. Remove the model: line if you would rather always use your session model. Codex and Pi do not use these fields to select a model. Choose the model in the client instead.

This repository is a Claude Code plugin marketplace. In your Claude Code session:

/plugin marketplace add NethServer/agents
/plugin install nethserver-skills@nethserver
/reload-plugins

For the frontend skills, also run /plugin install frontend-skills@nethserver. They have been tested in Claude Code and Codex (see below). Pi does not install them: it reads only the skills/ directory.

No plugin version is pinned, so every push to the default branch counts as a new version. Claude Code refreshes installed marketplaces in the background (this is a public repo, so the pull needs no credentials), so you pick up new and updated skills automatically — no reinstall needed. Force an immediate refresh with /plugin marketplace update nethserver.

These commands apply only to the Claude Code plugin install above:

/plugin uninstall nethserver-skills@nethserver
/plugin uninstall frontend-skills@nethserver
/plugin marketplace remove nethserver
/reload-plugins

uninstall removes the plugin but keeps the marketplace registered; marketplace remove also drops the catalog entry. After /reload-plugins the skills disappear from the / menu.

Codex can read this repository's .claude-plugin/marketplace.json and install the nethserver-skills plugin. Use a Codex CLI with the plugin and plugin marketplace commands, whose syntax was checked with version 0.157.0.

Run these commands in your terminal:

codex plugin marketplace add NethServer/agents
codex plugin add nethserver-skills@nethserver
codex plugin list --marketplace nethserver

For the frontend skills, also run codex plugin add frontend-skills@nethserver.

Confirm that the plugins are installed and enabled, then start a new Codex session. Use /skills or the $ picker to find the installed skills.

To refresh the marketplace and install its current plugin contents:

codex plugin marketplace upgrade nethserver
codex plugin add nethserver-skills@nethserver
codex plugin add frontend-skills@nethserver

Run the last command only if you installed the frontend skills.

Start a new Codex session after updating. For a pinned installation, add the marketplace with --ref instead of the first command above. Replace 0.0.3 with the published tag you want to use:

codex plugin marketplace add NethServer/agents --ref 0.0.3

Marketplace updates follow the configured reference. A fixed tag keeps the installation on that release until you explicitly select another reference.

For CLI details, see the Codex plugin commands and marketplace commands.

codex plugin remove nethserver-skills@nethserver
codex plugin remove frontend-skills@nethserver
codex plugin marketplace remove nethserver

The first two commands remove the installed plugins. The last removes the registered marketplace. Start a new Codex session after removal.

Pi discovers the repository's skills/ directory when installing it as a Git package, so it installs the nethserver-skills only, not the frontend skills. The commands below use the CLI syntax available in Pi 0.87.1.

Run these commands in your terminal:

pi install git:github.com/NethServer/agents
pi list

Confirm that the repository appears in pi list, then start Pi and type /skill: to find the installed skills. Personal installations are recorded in ~/.pi/agent/settings.json. To register the package for one project instead, run this from that project's directory:

pi install -l git:github.com/NethServer/agents

This records the package in .pi/settings.json. Pi loads project packages after the project is trusted.

To update this package:

pi update git:github.com/NethServer/agents

Run /reload in an active Pi session after updating, or start a new session. To install a specific release, append its Git tag. Replace 0.0.3 with the published tag you want:

pi install git:github.com/NethServer/[email protected]

Tags and commits stay pinned during updates. Run pi install with the new reference when you want to move to another release.

For package discovery and versioning, see Pi packages. For command options, see the Pi CLI reference.

pi remove git:github.com/NethServer/agents

Add -l when removing a project-local installation. Run /reload in an active Pi session after removal, or start a new session.

Automatic — when your task matches a skill's description, the agent may load it on its own. This is model-decided and not guaranteed; for a specific skill, name it explicitly (see below). Example prompts that tend to trigger a match:

"Review this Containerfile"

"Add a configure-module action to my ns8 module"

Once installed in Claude Code, everything is namespaced under the plugin (nethserver-skills:).

Slash menu — type / and pick the skill by name (e.g. /nethserver-ns8-module). The grey (nethserver-skills) label shown beside it is the source plugin, not part of the name.

Explicit — you can also invoke a skill by its fully-qualified name:

nethserver-skills:nethserver-ns8-module
nethserver-skills:nethserver-containerfile
nethserver-skills:nethserver-pr

In Codex CLI or the IDE extension, run /skills or type $ and select the desired skill from the picker, such as nethserver-ns8-module from nethserver-skills. Include the selected skill in your prompt and describe the task. See Codex skill invocation.

Use /skill:<name> to load a skill explicitly. You can append the task after the command:

/skill:nethserver-ns8-module Add a configure-module action
/skill:nethserver-containerfile Review this Containerfile
/skill:nethserver-pr Draft a pull request for the current changes

See Pi skill invocation.