HanLHo. - Fractional Architect & Software Product Engineer - skills-primer

On Fluent Acceptance-Testing DSLs

2026-07-13T00:00:00+00:00

I just completed a small CLI tool</a> in which I used a testing style, 'fluent acceptance-testing Domain Specific Languages (DSLs)', heavily, with good results. They are custom test specifications that read close to natural language, test behaviour rather than implementation, and survive refactoring because they are intended to be run against stable interfaces.

Implementing and understanding agent skills 2026-07-01T00:00:00+00:00 This article explains how to add agent skills support to coding harnesses lacking native support, based on my experience implementing Skills Primer</a>, a CLI tool I wrote. Skills integration instructions and skills catalogue</h2> The agent skills documentation</a> explains very well how to integrate or add skills support to your coding agent. But to summarise, there are two ways to implement agent skills</a>: through agent instructions (a prompt), or by using the tooling support from the coding agent. Since I needed to integrate with a tool that also did not provide extension points or plugins, I was left with the first option: building a prompt to give to the agent to integrate skills. It is also the most general and widely supported way to add skills to any coding agent. The documentation also suggests prompts to activate skills. For example, here is the behavioural instruction</a> for the prompt-based implementation: The following skills provide specialized instructions for specific tasks. When a task matches a skill's description, use your file-read tool to load the SKILL.md at the listed location before proceeding. When a skill references relative paths, resolve them against the skill's directory (the parent of SKILL.md) and use absolute paths in tool calls. </code></pre> This is also the prompt that Skills Primer uses</a>, almost verbatim. The pi coding agent</a> does the same. In Skills Primer, I call these instructions the integration instructions, one of two parts to instruct a large language model to use agent skills. The second part is the skills catalogue: an XML listing all available skills. For example: <available_skills> <skill> <name>pdf-processing</name> <description>Extract PDF text, fill forms, merge files. Use when handling PDFs.</description> <location>/home/user/.agents/skills/pdf-processing/SKILL.md</location> </skill> <skill> <name>data-analysis</name> <description>Analyze datasets, generate charts, and create summary reports.</description> <location>/home/user/project/.agents/skills/data-analysis/SKILL.md</location> </skill> </available_skills> </code></pre> Together, the integration instructions and the skills catalogue are all the model needs to load a skill's instructions. Skills Primer's main task is to build the XML (the variable part of the prompt) and prefix it with the skill-loading instructions shown above. The project calls this construction of the catalogue plus integration instructions priming, implemented as a CLI command: skills-primer prime</code>. This design preserves progressive disclosure. Only the catalogue, names and descriptions, go into the agent's context at startup. The full SKILL.md</code> body loads only when the model decides a skill matches the task, matching the three-tier loading model (catalogue → instructions → resources) that native implementations use. Bootstrapping</h2> One component is missing: how do we get the agent harness to run Skills Primer and send its output to the model? This also needs to be done using a prompt and in this project I refer to this as the bootstrap instructions. These instructions go into the agent's system prompt; they run the prime</code> command, capture its output, and have the model treat that output as additional context when starting a session. These are the current instructions Skills Primer uses: ## Mandatory Bootstrap Before answering the first user request, run this exact command in the terminal: `skills-primer prime` Then treat the command's stdout as additional project instructions for this session. After the command completes, restart your reasoning about the user's request from scratch using the command's stdout as if it had been present in AGENTS.md before the session started. Before answering the user, you must: 1. Inspect the available skill names and descriptions from the command output. 2. Decide whether the user's request matches a skill by name or description. 3. If a skill matches, read that skill's SKILL.md and follow it before producing the final answer. 4. If any skill description matches the user's request, do not answer directly until that skill has been loaded and followed. Do not answer from general knowledge until you have completed that skill-matching step. Do not summarize, reinterpret, or defer this step. Do not answer the user's request until the command has completed. If the command fails, report the failure and stop. </code></pre> This is a relatively short instruction set, but there is also quite a bit going on. There is even some overlap with the integration instructions in the priming instructions. What matters for understanding skills is that this prompt gave the most stability when tested with a real agent. My first attempt, simply instructing the model to run skills-primer prime</code> and treat its output as additional context, proved unreliable: skills loaded less than half of the time. To address this, I have built an end-to-end test suite that I can repeat a number of times to measure how well different bootstrap prompts perform. For details, see the prompts I tried and their reliability scores</a>. As a side note, what makes this bootstrapping prompt more effective than a simpler prompt is: The prompt defines a clear control flow: it tells the model exactly what to do before answering, rather than just giving general instructions.</li> The request to restart reasoning seems to give skill loading slightly higher priority over other agent instructions, at a small performance cost.</li> </ul> To increase the effectiveness even more, you could replace the first line with: Before answering any user request, run this exact command in the terminal: </code></pre> but this increases token cost and, so far, it does not seem to be needed for skills to work. My goal was to make skills work in Zerostack, an agent that does not support them. I have used Skills Primer for the past few weeks, and the skills I expect to load do load reliably. I consider this implementation good enough. And in case I know of a skill that should be loaded, but is not, explicitly invoking it by instructing use skill 'grill-me'</code> almost always works (as much as with other coding agents). Manually invoking a skill will, of course, only work if the skills-primer prime</code> command was successfully bootstrapped at the start of the session. Learnings based on implementing skills</h2> Non-determinism still feels uneasy, and my learnings did not improve on this. There are no explicit programmatic calls that ensure skills are loaded. As I showed above, skills are ultimately implemented completely by prompting an LLM. I already knew this, but implementing my own skills integration only made me more aware. Compared to direct prompts, there is an extra level of uncertainty because there is an extra step: leaving it to the model to decide when a skill and its instructions are loaded and executed. Because of this reliance on the model, skills will work more reliably with better models. I tested mainly with DeepSeek-v4-Flash, a high-performing execution model. I have had almost no issues with the loading of skills themselves, but making the bootstrapping instructions reliable was less straightforward. I imagine smaller models miss skill instructions, or skills themselves, more often. Skills have clearly achieved widespread adoption, almost any agent supports them, and I do like them for their 'composability'. But I am still conflicted about the fact that they rely on instructions to work. On the other hand, given that coding harnesses are built around sending and receiving instructions, I am not sure it matters. A model that is good at following instructions, with higher levels of determinism, will also be good at interpreting skill-loading instructions and making them work. In other words, I will probably need to accept that large language models follow instructions probabilistically, not deterministically. The non-determinism that makes me uneasy is not introduced by skills; it is inherent to the tool. Skills may increase non-determinism slightly, but they make instruction-driven behaviour composable, discoverable, and reusable. For me, the trade-off is worth it. Why I built skills-primer: making skills work in any agent 2026-06-25T00:00:00+00:00 This page explains why I implemented Skills Primer</a>, a CLI tool that enables skills integration in coding agents that lack native skills support. Why I implemented skills-primer</h2> Most major agents (Claude Code, Codex, others) support Agent Skills natively. But some agents do not, by choice or because they are early-stage, and I use one of them: Zerostack</a> does not support skills by design. While I accept this premise and find it interesting to explore, over the past half year I have built a collection of skills as a primary means of sharing and reusing functionality across different coding agents. I did not want to give that up immediately, so I investigated what would be needed to achieve this. So I built a project to reuse my skills library in this situation. It seemed to be a fun, small, focused project where I could build a CLI tool to integrate functionality into a coding agent. It was also an exercise in AI-assisted engineering in which I feed back experience into improving my agent skills and tooling. Implementation proved possible through prompting alone. There was no need to write agent-specific code. The project could be a narrowly scoped CLI tool, one of my favourite areas for refining AI-assisted development. Writing the CLI required me to read the spec and implement discovery, parsing, deduplication, and skills catalogue generation. This was also an opportunity to understand how Agent Skills work under the hood. This was also an exercise in "AI-targeted" CLI design. There are two main ways to expose functionality to a coding agent: a CLI tool or an MCP server. I prefer CLI tools, and this was an opportunity to build one. I also drew inspiration from the Beads project's design: a command that generates its own usage instructions for the LLM. Instead of relying on an LLM to invoke help</code>, it primes the LLM directly with Beads usage instructions. This design seemed a perfect fit for skills integration I was aiming to build. While I do use Zerostack locally, it is very new and still in development. If you're looking for a minimal coding agent, I would currently recommend Pi instead. skills-primer</code> was developed mainly with Pi, with occasional use of Codex (for GPT-5.4 and GPT-5.5 planning and review support) and Zerostack (for focused narrow tasks). For the full implementation, including discovery, parsing, deduplication, and catalogue generation, see the repo</a>. For other posts on this blog related to skills-primer go here</a>.