The NethServer agent skills should be findable from the developer manual

Development
1

@stephdl @davidep @giacomo

I have been building NS8 community modules with an AI coding agent for about three months. This week Stéphane pointed me to NethServer/agents, the agent skills with the NS8 module conventions. I only found them because he answered in one of my threads. I think they belong where module developers look.

Where they are not mentioned

  • Developer manual: searching the docs/ tree of ns8-core for “agents”, “skill”, “AI” and “Claude” returns nothing.
  • Development handbook: neither the “AI coding agents” section nor the Assisted-by: trailer in the commit message guide links to the skills.
  • ns8-kickstart: no AGENTS.md, no CLAUDE.md, no README line. An agent in a fresh module repository cannot discover the conventions.
  • GitHub code search for “NethServer/agents” in the organisation: one hit, the repository’s own README.

What the skills found in my modules

I checked all 19 of my modules against the ns8-module skill. They were built with the developer manual and by reading existing modules, and all of them worked.

  • 15 stored passwords, tokens or keys with agent.set_env(), so they ended up in Redis in plain text. The manual does not warn about this; the skill does. To put it in proportion: a good part were low-risk values, such as database passwords that are only reachable inside the pod, LDAP bind passwords of read-only accounts, and initial admin passwords meant to be changed after the first login. But not all of them: there were also session and JWT signing secrets, an OpenAI API key, an SMTP password, a Steam server token and the password of a timestamp signing key.
  • 12 had no restore-module, 7 no state-include.conf. A restored instance came up with fresh secrets and no settings.
  • 5 used rolling image tags.
  • One passed a key password on a container command line, visible in the node’s process list.

Combined with Stéphane’s QEMU test workflow (thread) it also found a module that could never be updated once configured: its state directory held files owned by a container sub-UID, and the core’s image extraction ends with a recursive chown. All of these modules had passed my manual install test.

The manual documents the platform contracts. The skills add the “do not do this” list the manual leaves implicit, which is what agents and newcomers need, provided they can find it.

Suggestions

  1. A short “Coding agents” page in the developer manual, next to “Testing”: what the skills are, what each covers, how to install them.
  2. A link in the handbook’s “AI coding agents” section.
  3. An AGENTS.md in ns8-kickstart pointing to the skills. Every new module starts from that template, and the agent reads that file first. Probably the change with the largest effect.
  4. On the “Testing” page, a pointer to the QEMU workflow. As Stéphane explained in his thread, the ns8-github-actions test workflow linked there needs the Nethesis DigitalOcean account and has never run outside Nethesis.

I am not part of the dev team and will not open pull requests against your repositories, but I can draft the manual page and post it here for you to edit.

Three questions

  1. The handbook asks for Assisted-by: AGENT_NAME:MODEL_VERSION in commit messages. Should community modules follow that? Mine used Co-Authored-By: until today, I have switched now.
  2. “Clone and Move” is on the certification checklist, and the reference modules symlink clone-module/50configure-module to the restore step. None of my modules had a clone-module action. The skill covers it in the backup reference under “Clone vs restore”, but neither my agent nor I picked it up there. Since a missing clone step fails silently, would a line under “Always applies” make sense?
  3. I come from pharmaceutical quality, where we typically have a reviewer pool. Reviews with standards as high as @stephdl’s are only as valuable as reviewers are available: if nobody reviews a pull request, the author will merge it unreviewed after a while. Is there a way to arrange reviews within the community?

Thanks to @stephdl for the skills, the CI workflow and all the help today.

@mrmarkuz I do need a reviewer on GitHub. What do you plan for the next few days? :slight_smile:

Best
Thorsten

2

Kickstart? You should have started from mine :slight_smile:

I put some “CLAUDE.md” files in there to help AI agents. AI agent-driven development is still quite new, though, and I agree that agents need to be guided, especially because I’m concerned about people using them to produce code without any framework, guidelines, or direction.

The skills has not been my idea first but from @Tbaile IRC but I recall my claude the first time I did /nethserver-ns8-module I feel like it got drug and went direct to the goal :slight_smile:

With AI agents, we basically have superpowers, but no idea where to go.

You can be the Joker or Batman. It mostly depends on what you do with that power.

I’m trying to share and discuss these ideas with others too. You can have a look here:

I never thought I’d see the day when this would become a real topic, but here we are :wink:

3

There is another problem we need to think about: reviewing code produced by AI agents.

An AI agent can keep producing code endlessly as long as we keep paying for tokens. Humans don’t have that luxury. At some point, our brains start overheating.

So we also need ways for agents to test and verify their own work, rather than relying entirely on human review.

For example, Claude can use review skills such as “/code-review” to review the code it has produced in the current branch.

You can also give it access to the application through the Chrome DevTools MCP, so it can actually interact with the application or the Cluster Admin UI through Chrome.

With the “nethserver-admin” skill, Claude can connect to the server over SSH and monitor the logs while it is using the application.

You can also ask the agent to write a QA checklist and then follow it step by step, just like a human tester would. The difference is that the agent can systematically validate many more scenarios and repeat the checks without getting tired.

This gives the agent a way to test what it has built, check the logs, and catch issues before asking a human to review everything.

The human review is still needed, but we can make it much more efficient by letting the agent do much more of the verification work first.

1 Like
4

excactly, but thats what I mean more deep your some module template rather than on top. I selected something, but that did not contain - thinks like that should be prone, more accessbile on top, particulary, it should be in the dev handbook

5

While I see the appeal of offloading repetitive verification to keep human brains from overheating, I have strong reservations about letting an AI validate its own work across multiple stages.

In traditional development and regulated industries, the standard workflow—Create → Review → Release—works because it relies on true separation of duties. Two different people bring different biases, mental models, and blind spots.

Simply attaching a /code-review skill or an MCP browser tool to the same underlying LLM does not create a genuinely independent reviewer. An agent will easily reproduce its own systemic blind spots, validate flawed assumptions it made during the build phase, or “hallucinate green lights” in edge cases. A judge cannot review their own sentence, even if they put on a different hat.

Coming from a perspective of process validation (such as Computerized System Validation / GxP in pharma): a process is only deemed valid if it deterministically and reproducibly yields the exact same quality within a defined design space—regardless of whether it is operated by humans or machines. With LLMs, we currently lack that deterministic reproducibility; the system’s internal state, probabilistic outputs, and drift mean we cannot formally validate the “reviewer” agent’s reliability.

Automated agent checks are great as pre-commit linting or extended smoke testing, but critical control gates must remain strictly in human hands until we have deterministic, verifiable output guarantees. In critical infrastructure—and NS8 manages core IT services—an agent should assist or prepare tests, not act as the independent QA authority that signs off on its own code.

And yes, I am fully aware that this partly contradicts my own recent practice—I’ve pushed AI-generated modules straight into NS8 myself! But as we explore these tools, one is allowed to change hats and reflect on the risks before we turn this into our default workflow. :grinning_face_with_smiling_eyes:

6

I enjoy french cusine with pleasure, I love french wine, but please do not expect me to speak your language.

1 Like
7

Surely your browser can translate?

1 Like
8

Look, I read a lot, but rarely LinkedIn and certainly not in French. Besides, feeding French into a translator feels like an irresponsible waste of global compute resources.

Think about it: French spends centuries writing letters at the end of words that nobody ever intends to pronounce. Imagine the environmental impact! How many LLM tokens, ink barrels, and entire forests of paper could humanity have saved if French had just stopped printing silent final letters?

I once had this exact debate with a Frenchman over the word Pizza. He insisted: “Non, you pronounce it Pizz’.” I replied: “Great, then let’s just drop the ‘a’ at the end to save space.” He looked horrified: “Non, impossible! If you drop the ‘a’, it becomes Pih’'!” (or whaterver he tried to say)

Until French language optimizes its token-to-phoneme ratio, my browser remains strictly on standby. :wink:

9

To keep the debate scientifically balanced: we Germans aren’t entirely innocent either.

We obsessively chain separate words together like LEGO bricks until they form majestic lexical freight trains like Donaudampfschifffahrtsgesellschaftskapitän (literally: “Danube steamship company captain”).

Sure, any modern LLM tokenizer starts hyperventilating and burns through 12 tokens just trying to split the syllables, but you have to give credit where credit is due: we save whitespace. In the printing press era, omitting those spaces saved precious paper.

French burns ink on silent letters; German saves paper by eliminating spaces. We are both absolute nightmares for compute budgets, just with different architectural flaws. :ship::germany::baguette_bread:

10

A Sauerkraut eater quarrel with a Baguette carrier about language?

Where I put my popcorn bin?
:slight_smile:

1 Like
11

Baguette and Kraut is very tasty. But du you know heaven and hell?

Heaven is where:

● the French do the cooking,

● the Italians do the loving,

● the English keep the peace,

● the Germans fix everything,

● and the Swiss organize the show.

Hell is where:

● the English do the cooking,

● the Swiss do the loving,

● the Germans keep the peace,

● the French fix everything,

● and the Italians organize the

Just playing with common stereotypes. here (close to Basel) we have 4 languages:

Englisch with Swiss accent,

English with German accent,

English with French accent,

Englisch with other accents.

12

Thanks for the detailed write-up and the questions.

On the Assisted-by trailer: yes, using it as the handbook suggests is the right call[1]. The point of that trailer is to keep the responsibility on the person, not the tool. Whatever wrote the code, it’s your commit and your name on it. Agent self-review can help you write better code, but it’s not a replacement for you as the developer actually checking and standing behind the work.

On clone vs. restore: they’re not the same thing, even if in practice they often end up looking alike or even sharing the same code. Whether they overlap a little or a lot depends on the app itself. So it’s worth treating them as two separate questions when you build a module, not assuming one covers the other.

On reviews: there’s already an established path for this, the Application Community Certification[2], which ends with the app being listed in the NethForge repository. You’re not required to go through it — you’re free to just ask a friend to look over your code and keep working in your own repository — but if you want a recognized, structured review process, that’s the one that already exists.

On the existing docs and conventions: with the newest Claude CLI versions, a separate CLAUDE.md file shouldn’t be needed anymore — the tool can now read AGENTS.md directly on its own. So we don’t need to keep both files in sync. That said, I’d be careful about pre-filling AGENTS.md with a lot of scaffolding, since keeping it up to date with ongoing core changes takes ongoing work, and it’s easy for it to go stale. I think each app’s AGENTS.md should stick to describing that specific app — not general platform rules, which belong elsewhere and shouldn’t be duplicated in every module. What I do agree with is making the links to the NethServer/agents repository easier to find from the docs, so people know where to look for the general conventions.

  1. Best Practices | Developer handbook ↩︎

  2. Community Certification | NS8 dev manual ↩︎

2 Likes
13

Mr Bernie Ecclestone had a quite different beliefs on that. Look for Pasquale Lattuneddu :slight_smile:

Heaven and hell are like code. Most of the times, human inventions.

14

Mr Bernie Ecclestone had a quite different beliefs on that. Look for Pasquale Lattuneddu :slight_smile:

And as for the opposite case: Switzerland clearly demonstrates that being Swiss does not automatically make you a capable organiser. Just look at Gianni Infantino. An exception that proves the rule — although, to be fair, his name does sound suspiciously Italian already.

But at least we can agree on one thing: English food belongs in hell. :wink:

And by the way, our languages all ultimately trace back to the Romans. As any Latin scholar will tell you:

Romanus eunt domus!

The languages may be different, but the meaning is remarkably consistent:

German — Familie
English — family
French — famille
Italian — mafia
Swiss — FIFA

15

image
image640×480 111 KB

2 Likes
16

I agree on both as Davide already said.

I would like to see this work integrated inside the NS8 by default.
Steph, when you have some time, please go ahead with integrating it inside NethServer/ns8-github-actions repo.

1 Like
17

Yes agreed, but responsibility is not my point - it is allways with the coder / developer and if you follow ISO 27001 (ISMS) the core is to put responsibility on where it belongs. But my point is different: Please do not forget non professional developers / hobbists like me. Not spending 8 h / day on a keyboard.

Even as such you need overview. IMO, we are discussing at which deep of documentation some item should be found. I pledge for “more on top”, in the process description. Actually, I would even prefer only “one big fat developer manual” with registers over several interlinked sites - all in one place. But that is personal flavour.

By the wey, I recently found this on German ct 2026/16:

https://www.heise.de/select/ct/2026/16/2616009265369757822

Sorry, I must not place the picutre here itself. For those who are not firm with German:

Boss: I was watching an AI writing 1000 lines of code per minute … can you do the same?
Developer: Yes, of course - I could even watch an AI writing 2000 lines of code per minute!

18

with great pleasure