Beyond "Chat": Architecting Intelligence with Skills and Specification Engineering

A developer argues that the industry's reliance on 'Mega-Prompts' is a technical dead end, advocating instead for a shift from prompt engineering to context engineering. The approach, demonstrated through work on the Vibrisse Agent, uses XML tagging to separate instructions from context and employs 'good vs bad' examples to stabilize output, especially for edge AI models running in the browser.

Remember the days when we used to dump all our CSS and JavaScript into a single index.html file? That's exactly what a "Mega-Prompt" is today: an unmanageable monolith. A few weeks ago, while working on the orchestration of Vibrisse Agent https://github.com/QuentinMerle/vibrisse-agent my local AI agent , I hit this exact wall. I was trying to stabilize a complex task by adding instructions to a 500-line system prompt. The more rules I added, the more the model forgot the older ones. The industry has sold us the myth of the Mega-Prompt. Those famous "50 ultimate prompts" or massive blocks of incantatory text are a technical dead end. Creative writing doesn't scale in production. As a web developer, my conviction is simple: to build reliable applications, we must stop "talking" to the machine and start configuring it. This is the shift from Prompt Engineering to Context Engineering . The first mistake with LLMs is mixing instructions the logic and context the data into an unstructured stream of text. It's the cognitive equivalent of spaghetti code. The solution? A strict separation of concerns. A highly effective technique documented by Anthropic, but applicable to any model, including local SLMs , is XML Tagging . Here is the "dirty" approach classic chat : You are a security expert. Analyze this authentication code, be strict, don't write a summary, check for XSS and SQLi vulnerabilities. Here is the code: function login { ... } And here is the "engineering" approach: <role Application Security Expert</role <instructions 1. Analyze the code provided in <context . 2. Identify vulnerabilities focus: XSS, SQLi . 3. Do not produce an introductory summary. </instructions <context function login { ... } </context Typing the language via tags creates clear boundaries. The model knows exactly where the directive is and where the data is. Even with clear instructions, AI can drift in output format or tone. This is where managing by examples exemplars comes into play. Giving the AI a concrete example of the expected behavior Good Example versus the behavior to avoid Bad Example is often much more powerful and token-efficient than adding 15 lines of theoretical instructions. Simply add an examples section to your XML structure: <examples <example <input Review of Button.tsx component</input <good output Line 42: The aria-label attribute is missing for accessibility.</good output <bad output This component is really well written, good job. However, accessibility could be improved.</bad output <reasoning The good example is surgical and actionable. The bad example is wordy and subjective.</reasoning </example </examples This "Good vs Bad + Explanation" pattern acts as a behavioral safeguard. This is especially critical in Edge AI. If you run a small 3B parameter model directly in the browser e.g., our demonstrator Vans using window.ai and @mlc-ai/web-llm , the model has reduced reasoning capabilities. Providing an XML js // Example of an Edge AI call via window.ai const response = await window.ai.createTextSession .prompt <instructions Analyze the accessibility of this component according to WCAG standards.</instructions <examples ...</examples <context ${domNode.outerHTML}</context ; 💡 The Craftsman's Tip:Treat your prompt like a configuration file. If your overall context exceeds 200 lines, it's no longer a prompt, it's a monolith. It's time to break it down. This is where the concept of Skill comes in. As the IBM team explains very well, we must distinguish semantic memory facts, often managed via RAG from procedural memory the how . Think of an LLM as an airplane pilot. The pilot intrinsically knows how to fly reasoning capabilities . But before taking off, they need the specific checklist for their aircraft the Skill so they don't crash. You don't hand a Boeing 747 manual to a Cessna pilot. Instead of loading all your agent's capabilities into a single prompt, the idea is to encapsulate each capability into a Skill . A modern Skill is no longer just a simple text file; it's a true versionable "plugin". It generally takes the form of a folder containing a main instructions file SKILL.md with its Front Matter, a standard pushed by agentskills.io , but also potentially business scripts and reference examples. Here is the typical anatomy of a Skill's central SKILL.md file: --- name: obsidian-researcher description: Trigger this skill to search for information in the user's Obsidian vault. tools: - mcp obsidian search - mcp obsidian read note --- Instructions 1. Use the mcp obsidian search tool with the user's query. 2. If a file seems relevant, read it using mcp obsidian read note . 3. Synthesize the notes found, without inventing facts use quotes . Notice the tools key in the Front Matter. This is one of the most powerful concepts in Specification Engineering: tool scoping . Rather than giving your AI agent global access to 50 tools which increases the attack surface and dilutes the model's attention , you restrict its arsenal to what is strictly necessary for this specific task . The skill becomes the secure entry point to an external MCP server, a local Python script, or a simple URL. This Progressive Disclosure approach revealing information to the model only when strictly necessary is vital in local AI. When you run a Llama 3 or a Gemma on your own hardware, every token counts. Loading only the procedural "brain" relevant to the context saves VRAM, speeds up inference, and drastically reduces hallucinations. A good Skill is a step-by-step procedure you could hand to a human intern. If the human doesn't understand, the AI will hallucinate. While Skills act as on-demand procedural memory, the agent still needs an identity and global rules. This is where structure files come into play: AGENTS.md : Defines the agent's identity, tone, and scope. This is the root context. DESIGN.md : Casts your absolute standards in stone. For example, instead of repeating "write accessible code" in every skill, your DESIGN.md stipulates the A11Y rules or performance constraints e.g., 60fps that apply everywhere.The agent then becomes a conductor. Faced with a request, it combines its AGENTS.md , its DESIGN.md , then dynamically selects the right SKILL.md loading it into active context , and executes it, often by calling external tools via the Model Context Protocol MCP . But the greatest advantage of this entirely file-based architecture is governance . Updating your AI's behavior is no longer a nebulous conversation lost in a chat history. It's a Pull Request . You can run a git diff between two versions of an AI procedure. For an engineering team, this is the ultimate argument for security and maintainability. This is exactly the approach we favor on our projects to manage complex behaviors without losing control. If we claim that AI behaviors are code, we must follow through with the engineering process. Two pillars are missing to close the loop: 1. Structured Output JSON Schema and Function Models: A skill must act like an API. If the AI politely responds "Here is your result: { ... }", it breaks your pipeline. In local AI, the prompt is not enough. You must constrain the SLM's generation via Outlines , XGrammar , or Ollama's native JSON mode to mathematically guarantee that the output will respect your schema. The agent no longer generates free text; it produces deterministic data. Furthermore, the industry is now moving towards the use of Function Models like FunctionGemma or the Hermes series . These models are specifically trained not to converse, but to parse parameters, call tools, and return valid JSON. It's the logical evolution: the language model becomes a simple API execution engine. For example, on our narrative RPG engine GemMaster , instead of a theoretical action schema, here is how we force the model to generate our NPCs in a strict format expected by the game: GemMaster: Force strict JSON response for NPC creation schema = { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "class": { "type": "string" }, "background": { "type": "string" } }, "required": "name", "class", "background" } } response = generate model="google/gemma-2-9b-it", Exact model to capture indexing prompt=skill context, format=schema The sampler rejects any token outside the schema 2. Systematic Evaluation Evals : You don't approve a Pull Request on a Skill based on a "gut feeling". Evaluating agents has become a discipline in its own right LLMOps . A behavior modification must strictly pass regression tests before being merged. Tools like promptfoo allow you to run your agent against a test dataset and evaluate assert whether the new skill regresses on edge cases. It is this rigor that separates "magical" prototyping from industrial production deployment. Our profession as web developers is evolving. We will write fewer isolated functions and architect more behaviors. To summarize: index.html . Type your prompts with SKILL.md with strictly scoped tools. AGENTS.md and DESIGN.md .Local AI coupled with a strict architecture allows us to maintain total control over our business logic: zero API costs, no data leaking to the cloud, and absolute sovereignty. Cloud AI remains exceptional, but for critical business workflows where predictability is king, execution control takes precedence. Magic doesn't exist in software engineering. There is only structure. And you, how do you version your agents' behaviors? Are you still stuck in the nightmare of mega-prompt maintenance, or have you started the transition towards skill orchestration? Proudly developed in Beauce, Québec 🇨🇦. Interested in the alliance between immersive web engineering and local AI sovereignty? Let's connect via Vibrisse Studio