Adding AI agent development guidelines to stephdl ns8-kickstart modules

Development
1

Hi everyone,

I’ve been experimenting with giving AI coding agents a clear set of development guidelines for NS8 modules, so they can contribute meaningful code while respecting our conventions instead of reinventing the wheel.

The idea: a small set of AGENTS.md / CLAUDE.md guide files committed at the root of a module. They describe the NS8 architecture, the authorization model, backend patterns (action handlers, journald logging, secret handling, backup), and frontend patterns (Vue/Vuex/Carbon, ns8-ui-lib component priority, i18n rules). When an agent works on the module, it reads the guide matching the layer it’s touching — backend or frontend — before writing any code.

I’ve opened two PRs adding these definitions to the kickstart modules:

These files are documentation only — no runtime impact. The goal is consistency: any agent (or new human contributor) picking up the module starts from the same best practices.

Happy to hear your thoughts. Does this look useful to standardize across NS8 modules? Anything you’d add or word differently?

Thanks!

2 Likes
2

I can see how this is useful for development.

However, since I don’t develop or create modules, I don’t see any immediate use case for myself.

It might have helped to support the AgentZero update process programmatically if comparable information about the architecture or update process had been available in the module. That’s why I wasn’t able to do it. Ai Agent: Agentzero - #48 by capote
@oneitonitram @Stll0

I’m also wondering whether it wouldn’t make sense to support both the agent-based system management of NS8 itself and that of the individual modules by providing structured information, as in AGENTS.md.

So far, I’ve made do by referring to the respective documentation (Nethserver docs or GitHub). But depending on the size of the context window and the general capabilities of the LLM being used, this may or may not work.

In particular, when container boundaries are crossed (e.g., log analysis, restarting services on the host or in other modules), this would improve the targeted operation of agents, token efficiency, and speed.

It was quite a challenge at first to make the agents understand that they are running in a container under NS8 and not on a standalone system using native Docker (e.g., management via runagent rather than podman).

Some of the trial-and-error involved in the agents building their own knowledge could be shortened.

Regardless of that, I’d be generally and fundamentally interested in hearing about your experiences with agent-based support.

I still think we could improve the learning curve for beginners here if we could compile a set of best practices or general guidelines with regard to the agent-based systems available here—AgentZero and Hermes Agent.

In my case, at any rate, it was quite a bit of fiddling around before I had more or less figured out how to get started and build meaningful use cases.

But since even Linus Torvalds supports the use of AI, I think the topic will continue to gain momentum and that reservations about it can be further reduced.

3

As I can’t realistically go back to riding a horse unless fuel becomes unavailable in Europe (which might happen sooner than we think :grinning_face_with_smiling_eyes:), I don’t think AI is going anywhere.

Today, anyone with a €20/month subscription can start writing code. Rather than fighting that, I’d rather help them become good NS8 developers. :grinning_face_with_smiling_eyes:

more calm answer

I think you’re raising a very good point.

From my perspective as a developer, I see AGENTS.md less as documentation for humans and more as a way to transfer project-specific knowledge to AI agents. It reduces the amount of code exploration they need to perform before they become productive, which saves both tokens and time.

I don’t think AI is a replacement for understanding the codebase. It’s more like having a junior developer available 24/7. Anyone can now pay €20/month and ask an AI to write code, but without guidance it will often produce something that doesn’t fit the project’s architecture or conventions. My goal is simply to help those people become better NS8 contributors.

I also agree that NS8 could expose more structured information about its architecture and execution model. Knowing that modules run inside containers, that operations should go through runagent, how services are managed, where logs are located, or how modules interact would help agents make much better decisions. Today, they eventually learn these things through trial and error or by repeatedly searching the documentation.

I believe there is value in documenting these conventions explicitly, whether that’s through AGENTS.md, project documentation, or another structured format. The important part is making the project’s assumptions easy to discover for both humans and AI.

Like it or not, AI is here to stay. Rather than resisting it, I’d rather make sure it helps people write better code and contribute in a way that respects the architecture and standards of NS8.

3 Likes
4

Thanks for This Will update the NEthserver 8 Modules Generator

To have this and also thinking of a way to embed ai into this Generator

3 Likes
5

I am pushing a skill to claude agent , with autoupdate :smiley:

6

I use this skill to give my agent knoledge about NS8. I find it very useful for debug and testing, but at the moment I only use it on dev machines. I don’t trust it in production.
What is really missing at the moment to use it on production is an MCP that allows read-only operations to the agent. I’ve made some experiment, but nothing rady to be released rn

1 Like
7

Awesome. Thanks very much!

8

Wow… that’s really impressive. Just load the skill, open the project’s codebase, provide the root@FQDN, and it uses your SSH keys. It’s like having a highly skilled sysadmin right there beside you.

Skynet is becoming real.

9

Thanks @stephdl for your continues effort and adding this to the template repository. I think it is a good start, although I still think if the documentation of the internals and how to administer things is better documented I am sure that all AI agents will benefit and be able to advise us better.

My main pitfall with nethserver8 is that it runs out of the box pretty smoothly and quickly but making customizations and adjustments is a challenge to me. While seeking assistance of AI I don’t get much further quickly as I have to keep teling it over and over again that Nethserver 8 is fundamentally different to Nethserver 7, which xomandset it is suggesting most off the time :sad_but_relieved_face:

1 Like
10

You’re right, and I think the gap is smaller than it looks.

These guide files are not a machine format. They are plain markdown: prose,
tables, commented code blocks. AGENTS.md explains why a pinned image tag
matters for Renovate, not just that it is a rule. A human reads it fine.

What is missing compared to real documentation is the packaging — the
introduction, the transitions, the worked examples, the repetition that helps
a reader who arrives cold. Not the content. So yes: hand the three files to an
AI and ask it to expand them into an administrator-facing document, and you get
something readable. The knowledge is already there.

Small note on the naming, so you find them in the repo: the files are
AGENTS.md, AGENTS-backend.md and AGENTS-frontend.md at the module root.
CLAUDE.md is a single line pointing at AGENTS.md.

On your actual pain point though — the agent suggesting NS7 commands on an NS8
box — those module files won’t help you. They target module developers, not
administrators. What you want is the nethserver-admin skill Stefano linked
above:

It ships the administration model: modules in rootless Podman, runagent
instead of podman, where the logs live. That is exactly the knowledge you are
currently re-typing into the chat every session.

Install the whole set as a Claude Code plugin:

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

The same plugin also bundles nethserver-ns8-module, which carries the same
guidance as the kickstart repos — architecture, authorizations, backend and
frontend patterns. So you can now start a module from scratch and let the agent
follow the conventions, without cloning a kickstart first. The kickstarts stay
useful as a working skeleton, but they are no longer the only way in.

If it still drifts back to NS7 answers after that, tell me which task — that’s
a concrete gap in the skill and worth fixing there rather than in your prompt.

1 Like
11

To me, this looks like the LLM/agent is disoriented because it’s trying to piece together knowledge from wherever it can find it.

That’s the simplest case, and all you need to do is throw the aforementioned NS8 administration skill in its face. My HermesAgent has pieced together a Hermes-specific skill from it.

In another case, you lured him onto the NS7 path yourself because he’s still finding outdated information in his memories that he considers relevant. In this case, you should audit his memories or skills.