Add AI skills in the scaffolds

[camilamacedo86]

What do you want to happen?

We might able to scaffold AI skill to help users work with the end solution for example.

Extra Labels

No response

[nerdeveloper]

i submitted a propoal for this which was later closed, so do you want me to reopen it?

[camilamacedo86]

i submitted a propoal for this which was later closed, so do you want me to reopen it?

I think we should evaluate the possibility of creating a specialized DevOps, Kubebuilder skill for Operators. We might also want to explore a separate skill focused on observability for Kubernetes operators, especially for code review use cases.

Before defining the solution, we should identify the most common workflows and the target personas. From my perspective, this seems slightly different from what you proposed earlier, unless I’m mistaken.

[camilamacedo86]

We might want here start for skills for Kubebuilder repo itself and then see if we want automate some process.
Aka review, bump of dependencies things like

[camilamacedo86]

The no vendoring way ( generic to work with any AI ) is by using SKILLS.MD , see; https://agentskills.io/what-are-skills

c/c @nerdeveloper (Just to share)

[rayowang]

/assign

[rayowang]

@camilamacedo86 Hi, camila,Thanks for raising this issue and sharing the context around AI agent skills!

I’ve been working on internal agent/skill-related tooling at my company recently, and I’ve spent some time putting together this initial implementation to address the issue.

I’ve submitted PR #5588 that adds a vendor-neutral SKILLS.MD at the repository level and scaffolds it into go/v4 projects, while keeping AGENTS.md for backward compatibility.

This is intended as a practical baseline for generic AI tools to understand project layout, commands, conventions, and common workflows. It’s kept minimal as a first step and can later be split into more focused, specialized skills.

Looking forward to your feedback!

[vitorfloriano]

For scaffolds, I think we should package skills in a plugin. Here's why:

What's an agent skill

At its core, a skill is a folder containing a SKILL.md file and relevant ancillary files. It works best when you organize the skills into separate subdirectories. Something like this:

.
└── .agents/
    └── skills/
        ├── kubebuilder-migration/
        │   ├── SKILL.md
        │   ├── from-v1-to-v2.md
        │   ├── from-v2-to-v3.md
        │   ├── from-v3-to-v4.md
        │   ├── migration-docs.md
        │   ├── any-relevant-info.md
        │   └── ...
        ├── crd-development/
        │   ├── SKILL.md
        │   ├── some-schema.json
        │   ├── something-else.yml
        │   ├── something-something-else.xml
        │   └── a-relevant-script.sh
        ├── k8s-api-server/
        │   ├── SKILL.md
        │   ├── more-relevant-files-here.md
        │   └── ...
        ├── controller-runtime/
        │   ├── SKILL.md
        │   ├── the-cr-api-or-something-like-that.json
        │   └── ...
        ├── another-relevant-skill/
        │   ├── SKILL.md
        │   ├── more-files.md
        │   └── ...
        └── some-operator-security-skill/
            ├── SKILL.md
            ├── some-important-security-practices.md
            └── ...

As we can see from example, it's not just a single file we add to root, much like AGENTS.md. It's a bunch of subdirectories, often with more than just one file, carefully designed for progressive disclosure (this is key).

As reference, see the official docs: https://agentskills.io/home

Caution

From the docs:

Start from real expertise

A common pitfall in skill creation is asking an LLM to generate a skill without providing domain-specific context — relying solely on the LLM’s general training knowledge. The result is vague, generic procedures (“handle errors appropriately,” “follow best practices for authentication”) rather than the specific API patterns, edge cases, and project conventions that make a skill valuable.

Effective skills are grounded in real expertise. The key is feeding domain-specific context into the creation process.

That said, we can mix both AGENTS.md and SKILL.md for the ultimate agentic AI development, guiding the agent to use specific skills for certain things. That is peak Agentic AI development! 🤖

My take

Since it involves adding A LOT of files, and considering it is all so novel and experimental, we should experiment that in the Kubebuilder repo first AND see if it improves agentic development.

If we see any benefits, then we can start working on a plugin.

WDYT?

[camilamacedo86]

Yes — I think of skills as instructions that guide the agent in a specific way.

AGENTS.md → overall behavior and general guidance
Skills → specialize the agent in a specific area

For example, a skill for writing Kubebuilder documentation makes sense because we already have specific conventions and style preferences. That would help the agent produce content aligned with how Kubebuilder documentation is normally written.

But we should first evaluate skills for Kubebuilder itself. If we find that they are helpful and bring clear value for maintainers, then we can consider whether it makes sense to add any end-user-focused skills.

However, something like this:

kubebuilder-migration/
├── SKILL.md
├── from-v1-to-v2.md
├── from-v2-to-v3.md
├── from-v3-to-v4.md
├── migration-docs.md
├── any-relevant-info.md

feels quite different. I do not think this kind of content should be scaffolded.

If I create a new project with go/v4, why would I want files about migrating from v1, v2, or v3? These files would not be relevant and would only add unnecessary noise.

Migration is typically a one-time action in a project’s lifecycle. Also, with alpha update and alpha upgrade, the old migration-step approach is even less necessary.

Because of that, migration guidance does not seem like a good fit for scaffolding.

[vitorfloriano]

If I create a new project with go/v4, why would I want files about migrating from v1, v2, or v3? These files would not be relevant and would only add unnecessary noise.

That makes sense. What skills are necessary for Kubebuilder and for the scaffolds are TBD.

But what I wanted to point out is that agent skills are usually comprised into several folders, with several files, not a single file (like AGENTS.md).

Can we put all the skills into a single SKILL.md file? Sure, we can. But that's not going to take advantage of progressive disclosure. A single SKILL.md file would either contain shallow instructions or it would be a huge file that would eat up the context window of the agent.

See this skill as an example: https://github.com/anthropics/skills/tree/main/skills/mcp-builder (it even has nested subfolders).

Also, the open standard explicitly defines skills as a collection of folders, not a single file: https://agentskills.io/what-are-skills

What are skills?

Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows.

At its core, a skill is a folder containing a SKILL.md file. This file includes metadata (name and description, at minimum) and instructions that tell an agent how to perform a specific task. Skills can also bundle scripts, templates, and reference materials.

my-skill/
├── SKILL.md          # Required: instructions + metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources

IMHO we should not to treat SKILL.md in the same way as AGENTS.md. It should be packaged as a plugin, considering the sheer amount of files that would be scaffolded.