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

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



Tópico: Beyond "Chat": Architecting Intelligence with Skills and Specification Engineering
Categoria: Tutoriais | Programação & Tecnologia
Idioma Principal: Português (Conteúdo de Tecnologia)

Descrição do Conteúdo / Informações:
-------------------------------------------------------------------------
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 (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.



Context Engineering: Typing and Structure


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.



The Power of Exemplars (Few-Shot Prompting)


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 few-shot is the only reliable method to force determinism without blowing up the context window:

// 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.



Procedural Memory: "Skills"


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.



Orchestration and Global Context


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.



The Engineer's Loop: Constraints and Evaluations


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.



Conclusion & TL;DR


Our profession as web developers is evolving. We will write fewer isolated functions and architect more behaviors.

To summarize:

•   Stop the "Mega-Prompts" (your catch-all index.html). Type your prompts with XML Tagging.

•   Use Few-Shot Prompting to frame the tone.

•   Break down your business logic into Skills (folders structured around a SKILL.md) with strictly scoped tools.

•   Manage global context with AGENTS.md and DESIGN.md.

•   Constrain the output (JSON Schema) and test your behaviors (Evals)!

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!