skills: Introduce cdba Codex skill

[quic-bjorande]

cdba can be used directly from e.g. Codex to integrate board automation tasks in the agent's workflow. Introduce the cdba Codex skill to facilitate this.

[superna9999]

I don't understand why this is actually needed, because 99% of SKILL.md should be in the main README file. Please just move all this to the main README and just reference for to whatever AI agent needs it.

[andersson]

Are you suggesting that I have a SKILL that states that the information needed is in the README, or that I just tell the agent to go read the README when I want it to use cdba?

You're right in that a fair amount of the actual information does belong in the README, but there's some things which I've added just to counter non-human behavior.

[superna9999]

Are you suggesting that I have a SKILL that states that the information needed is in the README, or that I just tell the agent to go read the README when I want it to use cdba?

The SKILL is written in human language and is actually very useful for humans for a README with plenty of example & so on.

You're right in that a fair amount of the actual information does belong in the README, but there's some things which I've added just to counter non-human behavior.

The only one I see is:

- Never invoke multiple `cdba` commands in parallel for the same host and board (for example, do not run `-l` and `-i` concurrently for one target).

And this is simply not true, running the same command in parallel for the same host and board will simply wait for the board to be released by the other user. Just document this fact.

I'm kind of annoyed of those imperative "Do ..", "Do not...", "Keep ...", "Use ..." sentences which could be normal sentences like:

• The next cdba command should be started only after the previous one has fully exited and its result has been handled.
• The cdba operations should be treated as single-flight for a host/board pair.
• Do not redirect or pipe interactive cdba output (>, >>, |, tee) unless the use-case explicitly requires it.
• The process should be kept in a TTY/session that allows sending keys and seeing UART output in real time.
• stdin is used to interact with the board and to exit cleanly with Ctrl+a, then q.

Why would be instruct and document the tool differently for humans and LLM agents ???

[lumag]

I think it still might be useful. At least if it plugs directly into the tool, it's worth getting it in.

[konradybcio]

I'm kind of annoyed of those imperative "Do ..", "Do not...", "Keep ...", "Use ..." sentences which could be normal sentences like:

• The next cdba command should be started only after the previous one has fully exited and its result has been handled.
• The cdba operations should be treated as single-flight for a host/board pair.
• Do not redirect or pipe interactive cdba output (>, >>, |, tee) unless the use-case explicitly requires it.
• The process should be kept in a TTY/session that allows sending keys and seeing UART output in real time.
• stdin is used to interact with the board and to exit cleanly with Ctrl+a, then q.

Why would be instruct and document the tool differently for humans and LLM agents ???

Agents expect to be commanded this way, unlike humans which can generally think for themselves. This is a skill definition, think of it as meta-programming a utility, so simple terms (vide caveman mode) are useful (if not necessary) to get a reasonable outcome.

• Never invoke multiple cdba commands in parallel for the same host and board (for example, do not run -l and -i concurrently for one target).

If we tell that to the robot beforehand, it will not waste large amounts of time finding that out itself (which is often blocking and doesn't get remembered for future reference)

[andersson]

If we tell that to the robot beforehand, it will not waste large amounts of time finding that out itself (which is often blocking and doesn't get remembered for future reference)

This is exactly the reason for that sentence, my agents kept trying to launch cdba to attach to the console of the running device, to see what it was doing, or to run some additional commands etc - and then it would be all confused about the fact that the board was busy.

[superna9999]

My comment still stands, a properly written readme for humans is still required, as you may notice we are the end users of all this at the end. I expected some minimal effort to bump the readme to the same level instead of concentrating on playing with codex and other generative AI tools and excluding humans of the game.

[lumag]

@superna9999 I understand your concerns, but I think those are two different topics. A skill file is useful, because it can just be combined with tools, improving the development practices. For example, I approved this PR after adding this skill to Claude's config and letting it figure out the kernel crash. In the end, humans can read SKILL.md and behave efficiently. AI tools are less efficient if faced just the README.md

[andersson]

a properly written readme for humans is still required

Absolutely agree with you @superna9999, the current "documentation" is no good - and that's a problem for both humans and robots. I've started restructuring and improving this. It's still work in progress but I will try to get this over the finish line soon.