DEV Community: NEXT4I DEV

How to Write an AI Agent Skill File That Reduces Guesswork

NEXT4I DEV — Mon, 14 Sep 2026 16:58:08 +0000

A prompt can tell an agent what to do once. A skill file can document how a team handles that class of work repeatedly.

For developers, the distinction matters. An agent may have repository access and the right tools, yet still has to make decisions about scope, references, validation, and failure handling. If those decisions are undefined, a technically valid result can still be the wrong result.

This guide builds a small, generic skill for reviewing API changes. The point is not to prescribe one universal Agent Skills format. It is to show how to turn vague intent into an executable workflow.

Skill discovery, instruction loading, and tool use vary by model, agent runtime, system instructions, and available tools. Treat the structure below as a portable design pattern, then adapt it to your platform.

The problem with a reasonable instruction

Consider this prompt:

Review this API and make sure it follows best practices.

It sounds clear, but the agent still has to decide:

Which API contract is authoritative?
Does the review include authentication and permissions?
Should it modify code or only produce a report?
Which tests should it run?
What should it do when information is missing?
What does a completed review contain?

Different models may fill those gaps differently. The result can be reasonable without matching the workflow you intended.

Prompt versus skill

I use this distinction:

A prompt says, “Do this task now.”
A skill says, “This is how we handle this type of task.”

A useful skill does not make a model magically smarter. It makes the operating boundaries visible.

At minimum, it should define:

Trigger: when the skill applies
Goal: what outcome it should produce
Scope: what is included and excluded
Workflow: steps the agent can follow
References: information to read under specific conditions
Constraints: actions and claims that are prohibited
Uncertainty handling: what to do when evidence is missing
Completion criteria: how to validate the result

A practical directory structure

Start with one file while the workflow is small. Split it when references, examples, or reusable scripts become large enough to distract from the main instructions.

api-review-skill/
├── SKILL.md
├── references/
│   ├── api-contract.md
│   ├── security-rules.md
│   ├── output-examples.md
│   └── troubleshooting.md
├── scripts/
│   └── validate.sh
└── assets/
    └── review-template.md

The exact file names and supported directories depend on the platform and runtime. More importantly, models may not select or load these files in the same way. The main file should therefore explain why and when each reference matters.

A generic `SKILL.md` example

---
name: api-change-review
description: "Review API changes for contract compatibility,"
  security boundaries, and required validation. Use when an
  endpoint, request schema, response schema, authentication,
  or permission behavior changes.
---

# API Change Review

## Goal

Produce a review report that identifies contract-breaking changes,
security-sensitive changes, missing validation, and unresolved assumptions.

## Scope

Review the proposed change and related tests.
Do not modify implementation files unless the user requests edits.

## Workflow

1. Read the changed files and the API contract.
2. Identify changes to endpoints, fields, status codes, and behavior.
3. If authentication, secrets, or permissions are involved,
   read the security rules.
4. Compare the tests with the changed behavior.
5. Produce the required report.
6. Run the validation command when the environment supports it.

## Reference routing

- Read `references/api-contract.md` for endpoint or schema changes.
- Read `references/security-rules.md` for authentication,
  secrets, or permission changes.
- Read `references/output-examples.md` only when the report format
  is unclear.
- Read `references/troubleshooting.md` when validation fails.

## Constraints

- Do not invent endpoints, fields, metrics, or test results.
- Do not expose credentials, customer data, or internal URLs.
- Do not present an unimplemented requirement as released behavior.
- Flag assumptions that require human review.

## Required output

1. Summary
2. Contract-breaking changes
3. Security-sensitive changes
4. Missing or affected tests
5. Assumptions requiring review
6. Validation performed

## Completion criteria

- Every changed behavior is mapped to the contract.
- Security-sensitive changes are explicitly identified.
- Validation results state what was and was not run.
- Unresolved assumptions are visible.

This example is intentionally generic. It demonstrates an instruction contract, not a claim about one platform's required syntax.

Before and after

Before

Review this API and make sure it follows best practices.

After

Review the API change using the api-change-review skill.

Use `references/api-contract.md` as the contract source.
If the change touches authentication, secrets, or permissions,
also apply `references/security-rules.md`.

Produce the required review report. Do not modify implementation files.
State which validation commands were run and flag unresolved assumptions.

The second instruction is not better because it is longer. It is better because fewer operational decisions are left undefined.

Turn the index into a routing table

A file list tells an agent what exists. A routing table explains when a file becomes relevant.

Reference	Read when	Skip when
`api-contract.md`	An endpoint, schema, status code, or behavior changes	The task does not involve an API contract
`security-rules.md`	Authentication, secrets, roles, or permissions are involved	The task has no security-sensitive behavior
`output-examples.md`	The required report shape is unclear	The output contract is already explicit
`troubleshooting.md`	Validation cannot run or fails	Validation succeeds normally

This table is guidance, not an enforcement mechanism. Actual reference selection still depends on the model, runtime, context strategy, and tools.

Single file or multiple files?

Keep the skill in one file when:

it has one short workflow
all constraints fit without hiding the main steps
examples are small
no reusable scripts are needed

Split the skill when:

references are long or domain-specific
several workflows share the same rules
examples make the main file difficult to scan
validation scripts are reusable
sensitive rules require separate ownership or review

The main file should remain enough to answer two questions: What should the agent do, and where should it look next?

Treat skills like software

A skill can contain instructions, references, and executable code. Review an external skill before using it, especially when it can access files, call a network service, or run scripts.

Check for:

file access outside the expected scope
network and API destinations
hardcoded credentials
destructive file operations
hidden instructions that attempt to bypass system rules
scripts whose behavior has not been reviewed

For organizational use, sandboxing and coexistence tests may also be appropriate. Different models can respond to the same instruction or tool surface differently.

Validation checklist

- [ ] The description states when the skill should trigger.
- [ ] The goal and scope are explicit.
- [ ] The workflow contains observable steps.
- [ ] Each reference has a condition for when to read it.
- [ ] Prohibited actions and claims are listed.
- [ ] Missing information has a defined handling rule.
- [ ] The output contract is reusable and testable.
- [ ] Completion criteria can be checked.
- [ ] No secrets or internal URLs are embedded.
- [ ] Executable scripts have been reviewed.
- [ ] The skill was tested on tasks that should trigger it.
- [ ] The skill was tested on tasks that should not trigger it.

Final takeaway

Before handing a skill to an agent, read it as if you were a developer joining the project today:

Can I complete the work from this information? What would I still have to guess? If I must make a decision, do I know which direction to take?

A good skill does not remove reasoning. It removes avoidable guessing.

Read the canonical article on NEXT4I: https://www.next4i.com/dev-notes/en

What Is Token & LLM Cost Optimization

NEXT4I DEV — Mon, 07 Sep 2026 14:35:04 +0000

What Is a Token in LLMs? A Developer's Guide to Cost Optimization and Architecture

Understanding how LLM tokens work is the difference between an AI feature that costs $50/month and one that runs up a $5,000 AWS/OpenAI bill.

Here is the engineering breakdown of tokenization algorithms, input vs. output pricing asymmetries, multilingual overhead, model pricing dynamics, and six production strategies implemented at NEXT4I to cut inference costs by up to 50-80%.

#Buildinpublic, #ModelAI, #LLM, #AIArchitecture, #TokenOptimization, #AIDeveloper

1. What Is a Token Under the Hood?

LLMs do not process raw text or strings. They consume Tokens—subword representations mapped to high-dimensional embedding vectors via algorithms like Byte-Pair Encoding (BPE).

"Hello world" -> ["Hello", " world"] (2 tokens)
"Unstoppable" -> ["Un", "stoppable"] (2 tokens)

The Multilingual Token Penalty

Because vocabulary dictionaries are predominantly trained on English corpora, languages without whitespace delimitation (such as Thai) suffer severe subword fragmentation:

English: 1 Token ≈ 0.75 words (~4 characters).
Thai: 1 Word ≈ 3 to 8 Tokens (frequently split into byte-level representations).

A prompt written in Thai can cost up to 6x more in raw token usage and introduce noticeable latency compared to its English equivalent.

2. Formatting Mechanics: Linebreaks & The "Emoji Tax"

Every character in your prompt payload carries a token cost:

Newlines (\n) and Numbered Markdown:
- Consumes 1 token per newline.
- Verdict: Highly recommended. Clear formatting provides structural anchors for transformer attention heads, significantly reducing hallucination.
The Emoji Tax:
- Emojis are complex multibyte Unicode sequences, often consuming 2 to 6+ tokens each.
- Avoid embedding decorative emojis in static system prompts that execute millions of times.

3. Input vs. Output Tokens: Why Output Costs 3x–5x More

API rate cards price Output Tokens significantly higher than Input Tokens. Why?

Input Tokens (Parallelized Compute): Processed simultaneously across GPU tensor cores in a single matrix multiplication pass (Prefill / Encoding). It is fast and hardware-efficient.
Output Tokens (Sequential Autoregression): Generated one token at a time (Autoregressive Decoding). The model generates token N, appends it back to the context history, and re-computes attention for token N+1. This locks GPU resources over the entire generation cycle.

4. Why Model Pricing Varies by 100x (Dense vs. MoE Architecture)

You may have noticed that API pricing spans from $0.30 to $50.00+ per 1 million tokens across models:

DeepSeek-V4: $0.50 – $1.70 / 1M Tokens (Massive architecture, exceptionally cost-efficient)
Gemini 3.7 Flash: $0.30 – $1.80 / 1M Tokens (High-efficiency edge tier)
Claude Sonnet 5: $2.00 – $10.00 / 1M Tokens (Mid-tier balanced powerhouse)
OpenAI GPT-5.6 Terra: $2.00 – $12.00 / 1M Tokens (Enterprise mid-tier)
Claude Opus 5: $5.00 – $25.00 / 1M Tokens (Premium reasoning class)
Claude Fable 5: $10.00 – $50.00 / 1M Tokens (Mythos-class model from Anthropic)
OpenAI GPT-5.6 Sol: $4.00 – $30.00 / 1M Tokens (OpenAI's flagship)

Note: Model pricing per token fluctuates frequently across providers and should be used strictly for relative comparative analysis.

This pricing variance stems from three fundamental drivers:

1. Architectural Design: Dense Models vs. Mixture-of-Experts (MoE)

Dense Models

Mechanics: Every incoming vector/token is processed through 100% of the model's parameters, from the initial layer to the final output layer.
Analogy: Like a company where every single employee must sit in every meeting and vote on every decision—regardless of whether the task is simple arithmetic or legal compliance.
Trade-offs: Highly compute-intensive (massive FLOPs per token), resulting in higher per-token inference costs. However, memory management and GPU scheduling remain straightforward.

Mixture-of-Experts (MoE)

Mechanics: An intelligent gating mechanism called a Router (or Gating Network) acts as a dispatcher, evaluating incoming tokens and dynamically routing them to specialized sub-networks (Experts).
Execution Flow:
1. The Router analyzes each token and activates only a sparse subset of experts (e.g., selecting 2 out of 8 or 64 total experts).
2. Compute flows exclusively through the parameters of the chosen experts.
Analogy: Like a well-structured organization with an executive dispatcher. A calculus question is routed strictly to the math experts without distracting the linguistics team.
Advantages: Enables total model capacity (Total Parameters) to scale massively while keeping active compute per token (Active Parameters / FLOPs) extremely low. This allows lightning-fast generation and drastically lower API prices (e.g., DeepSeek, Mixtral).
Trade-offs: Requires massive VRAM/RAM pools to keep all expert weights loaded in memory simultaneously.

The MoE Achilles' Heel: When Routers Fail

While MoE unlocks unmatched cost efficiency, its performance is tightly bound to routing stability:

Loss of Nuance & Context Disruption:
- Natural language is rich with subtle subtext. If a router misinterprets a token and dispatches it to the wrong expert, nuanced meaning collapses. The output may stay grammatically intact but lose analytical depth or fail to address the core prompt intent.
Router Collapse & Expert Imbalance:
- Routers naturally develop bias toward a handful of frequently trained experts, causing severe load imbalance. The favored experts hit computational bottlenecks while neglected experts become Dead Parameters, defeating the entire purpose of modular specialization.
Cascading Errors:
- LLMs process representations layer by layer. If an early-layer router misroutes a token, downstream layers receive corrupted intermediate activations, amplifying routing errors across subsequent layers.

🛠️ Engineering Safeguards Used by Frontier Labs:

Auxiliary Load Balancing Loss: Incorporating penalty penalties into the loss function during pre-training to enforce uniform token distribution across all expert sub-networks.
Capacity Factor Enforcement: Setting strict token buffer caps per expert. Once an expert's capacity threshold is reached, excess tokens are spilled over to secondary experts to prevent execution bottlenecks.

2. Reasoning Overhead (Thinking / Chain-of-Thought Tokens)

Reasoning-focused models (like Claude Opus, OpenAI GPT Sol) generate thousands of internal, hidden Chain-of-Thought tokens before emitting their first visible output token. Providers meter and bill for every single background reasoning step.

3. Hardware Sovereignty & Custom Silicon

Hyperscalers operating proprietary custom silicon (such as Google’s TPU clusters for Gemini) achieve significantly lower baseline operating costs than providers renting general-purpose Nvidia H100/H200 GPU clusters.

5. 6 Production Strategies to Cut Token Costs by 80%

Here are some of the production-level strategies we use in building NEXT4I:

1. Prompt Engineering for Token Efficiency

Eliminate fluff and instructions that don't add semantic value. Use concise formats like YAML or Markdown instead of verbose JSON schemas.

2. Leverage Prompt Caching

Major LLM providers (Anthropic, OpenAI, DeepSeek, Google) offer prompt caching. Placing static context (system instructions, tool definitions, schemas) at the prompt root allows providers to cache the KV-cache, reducing input costs by 75%–90%.

3. Intelligent Model Cascading (Model Routing)

Never route every query to flagship models. Route simple classification, data extraction, and formatting tasks to lightweight models or budget-friendly models (Gemini Flash, DeepSeek), escalating only complex reasoning tasks to larger models (Claude Sonnet, GPT Terra, GPT Sol, Claude Opus / Fable).

4. Sliding Context Windows & Conversation Pruning

Chat histories grow quadratically ($O(n^2)$) if sent in their entirety on every turn. Maintain a rolling sliding window of the last 5–10 messages, or summarize older context into a single concise paragraph.

5. Pre-Retrieval RAG Filtering

In RAG pipelines, do not inject full documents into the context window. Use embedding similarity and rerankers to select top-k (3 to 5) chunks, applying semantic deduplication before prompt construction.

6. Multilingual Translation Layer

For bulk data extraction or batch processing on non-Latin languages, translating text to English with a lightweight model prior to deep inference on flagship models can reduce total token usage and improve execution latency.

Key Takeaways

+-------------------+---------------------------------------------------+
| Metric            | Engineering Reality                               |
+-------------------+---------------------------------------------------+
| Token Ratio (EN)  | ~1 Token ≈ 0.75 words (~4 characters)             |
| Token Ratio (TH)  | ~1 Word ≈ 3–8 Tokens (byte-level inflation)       |
| Cost Ratio        | Output is 3x–5x more expensive than Input         |
| Pricing Deltas    | Dense vs MoE, TPU/ASIC custom silicon, CoT tokens |
| Core Optimizers   | Caching + Routing + Windowing + RAG Filtering     |
+-------------------+---------------------------------------------------+

Treating tokens as finite compute bandwidth ensures your AI infrastructure remains fast, scalable, and economically sustainable.

Explore the NEXT4I journey and read the original article at: https://go.next4i.com/next4i/devnotes/en

The RAG War Story: How I Learned to Stop Worrying and Love Markdown

NEXT4I DEV — Tue, 01 Sep 2026 11:23:36 +0000

TLDR; When building an AI knowledge retrieval pipeline that extracts text from documents, I discovered that PDF is the worst format for AI and Markdown is the best. Here's the multi-step pipeline I had to build just to handle PDFs, why it was necessary, and the generic pattern you can steal to handle document ingestion in your own RAG systems.

The Problem: PDFs Are Pixel-Perfect Hell for AI Parsers

I was building a RAG (Retrieval-Augmented Generation) pipeline for NEXT4I the kind of system that reads your documents first, then answers questions from them. Standard stuff: document ingestion → chunking → embedding → vector search → LLM answer generation.

I chose a beautiful Thai tourism PDF as my test document. Professional design, complex Thai typography, images, tables, charts the works. Real-world document, real-world pain.

Here's what the naive approach looked like:

PDF File → PDF Parser → Extracted Text → Chunk → Embed → Search

And here's what actually worked:

PDF File
  ├─→ PDF Parser → Raw Text (broken Thai, missing punctuation)
  ├─→ Page Renderer → Full-Color Images
  │     └─→ B&W Converter → High-Contrast Images
  ├─→ AI Vision Model (color images) → Image Descriptions
  ├─→ AI Vision Model (B&W images) → Text Extraction
  └─→ Cross-Validation Layer
        ├─→ Multi-Model Synthesis
        ├─→ Spell-Check Model (critical for Thai)
        └─→ Human Review
              └─→ Final Structured Text → Chunk → Embed → Search

Why the complexity? Because PDF is fundamentally a presentation format, not a data format. When you extract text from a PDF, you're not reading structured data you're reverse-engineering a rendered page layout. For languages with complex typography like Thai (where vowels can appear above, below, left, or right of consonants, and tone marks float above), this is especially brutal.

The Generic Pattern: Multi-Path Document Ingestion with Cross-Validation

If you're building any system that ingests arbitrary documents, you'll inevitably hit the PDF wall. Here's the reusable pattern I settled on:

Architecture

                    ┌──────────────┐
                    │   Document   │
                    │   Ingest     │
                    └──────┬───────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │  Direct  │ │  Image   │ │  Image   │
        │  Text    │ │  (Color) │ │  (B&W)   │
        │ Extract  │ │  Render  │ │  Render  │
        └────┬─────┘ └────┬─────┘ └────┬─────┘
             │            │            │
             ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │  Text    │ │  Vision  │ │  Vision  │
        │  Output  │ │  Model   │ │  Model   │
        │          │ │  (Desc)  │ │  (OCR)   │
        └────┬─────┘ └────┬─────┘ └────┬─────┘
             │            │            │
             └────────────┼────────────┘
                          │
                          ▼
                 ┌─────────────────┐
                 │  Cross-Validate │
                 │  & Synthesize   │
                 │  (Multi-Model)  │
                 └────────┬────────┘
                          │
                          ▼
                 ┌─────────────────┐
                 │  Spell-Check    │
                 │  & Normalize    │
                 └────────┬────────┘
                          │
                          ▼
                 ┌─────────────────┐
                 │  Human Review   │
                 │  (Optional)     │
                 └────────┬────────┘
                          │
                          ▼
                 ┌─────────────────┐
                 │  Structured     │
                 │  Output → Embed │
                 └─────────────────┘

The key insight: no single extraction path is reliable enough on its own. You need multiple independent paths producing results, then a synthesis layer that cross-validates. Think of it like sensor fusion each path is a noisy sensor, and the truth emerges from the overlap.

Why Spell-Check is Non-Negotiable for Non-English Languages

For English, you might get away without a dedicated spell-check pass. For Thai where a single misplaced tone mark changes the entire word you absolutely cannot. OCR and vision models hallucinate characters constantly on decorated fonts or text-over-image backgrounds. A dedicated language model fine-tuned for spell correction is the difference between "usable" and "garbage."

The Real Takeaway: Markdown is AI-Native. Everything Else Is Legacy.

After building this entire pipeline, I had a moment of clarity. If that same document had been authored in Markdown:

## Top Destinations

| Province | Highlight | Best Season |
|----------|-----------|-------------|
| Krabi    | Islands   | Nov–Apr     |
| Chiang Mai | Mountains | Nov–Feb   |

See the [full itinerary](#itinerary) for details.

mermaid
graph TD
A[Arrive Bangkok] --> B[Fly to Krabi]
B --> C[Island Hopping]
C --> D[Return]

markdown

...the entire pipeline collapses to: read the file → chunk → embed → search. That's it.

No OCR. No vision models. No B&W conversion. No multi-path cross-validation. No spell-check model. No human review for format-induced errors.

Markdown is structured, plain-text, and both human-readable and machine-parseable by default. It's the only format where:

Headings are unambiguously # / ## not inferred from font size
Tables are | column | row | syntax not pixel grids
Diagrams are Mermaid text not flattened raster images
Code is fenced not monospaced-font heuristics

"And here is how the human user experiences it:"

Top Destinations

Province	Highlight	Best Season
Krabi	Islands	Nov–Apr
Chiang Mai	Mountains	Nov–Feb

See the full itinerary for details.

graph TD
    A[Arrive Bangkok] --> B[Fly to Krabi]
    B --> C[Island Hopping]
    C --> D[Return]

"In reality, we can't always control the documents we ingest, and we can't just ignore them because they might contain critical data. But if we were to start from scratch, Markdown is definitely the go-to choice."

How This Shapes Our Architecture at NEXT4I

At NEXT4I, we treat Markdown as a first-class format throughout our stack. When building AI knowledge retrieval systems for everyday users and organizations, we encourage Markdown as the source of truth and handle PDFs as a necessary-but-painful compatibility layer.

The design principle is simple: AI Integration by Design. Make AI a first-class citizen of your content architecture, not something you bolt on later and hope it works. The format you choose today determines the ceiling of your AI capabilities tomorrow.

Thanks for reading all the way to the end, I'll keep working on more articles like this.

Explore the NEXT4I journey and read the original article at: https://go.next4i.com/next4i/devnotes/en

What Is LLM Actually Doing? A Fellow Engineer's Take on Vectors, Next-Token Prediction, and Fail-back Routing

NEXT4I DEV — Tue, 01 Sep 2026 05:30:51 +0000

Why treating an LLM as a probability engine, not a brain, changes how you architect around it. The reasoning behind NEXT4I's AI layer.

#LLM #BuildinPublic #SystemArchitecture #AI #Model AI #AI Router #AI Stable

I used to wonder why the model confidently gives you a wrong number. It's not a bug in the traditional sense, it's the model doing exactly what it's built to do: predicting the next token from probability, with zero actual arithmetic happening underneath.

TLDR; An LLM (large language model) converts text into vectors (numeric coordinates in a high-dimensional meaning-space) and generates output via next-token prediction, sampled with parameters like top-k and temperature. Because it's fundamentally a probability engine and not a calculator or a database, I designed NEXT4I with automatic model fail-back routing and task-based model selection instead of trusting any single model as a source of truth.

The Mental Model: Vectors, Not Meaning

Every token gets embedded into a vector, often with hundreds or thousands of dimensions. Semantically similar tokens end up close together in that space. That's why semantic search (vector-based retrieval) can match "large flying animal consumes insects" to "big bird eats worms" even with zero shared keywords, unlike old-school lexical search (TF-IDF/BM25) which needs literal term overlap.

GPUs handle this well because they're already wired for massive parallel floating-point math (the same math used to shade millions of pixels per frame), so throwing billions of similarly-directed vectors at a GPU is a natural fit, not a coincidence.

Generation Is Sampling, Not Retrieval

Given a prompt, the model doesn't look up an answer, it samples one token at a time from a probability distribution. Two knobs matter in practice:

top_k: 2        # only sample from the top-2 most likely next tokens
temperature: 0.2  # low = deterministic/precise, high = creative/varied

Low temperature + low top_k gives you consistent, "boring" output, good for structured extraction. High temperature gives you variety, good for brainstorming, bad for anything requiring precision.

Why LLMs Hallucinate on Arithmetic

There's no calculator inside the model. It doesn't evaluate x * y, it predicts digits that are statistically plausible given the prompt, one token at a time. It gets 2 * 2 right because that pattern is everywhere in training data. It confidently botches large multiplication because it's still just sampling digits, not computing. This is exactly why production systems now delegate real math to a tool call (a Python sandbox, a calculator function) instead of trusting raw model output.

Core Value: A Generic Model-Tier Fail-back Router

Here's the simple pattern, stripped of any specific business logic, a reusable fail-back wrapper for any set of same-tier model clients:

package modelrouter

import (
    "context"
    "errors"
    "fmt"
)

// ModelClient is any backend that can answer a prompt.
type ModelClient interface {
    Name() string
    Complete(ctx context.Context, prompt string) (string, error)
}

// TieredRouter tries each client in a tier in order until one succeeds.
type TieredRouter struct {
    tier []ModelClient
}

func NewTieredRouter(clients ...ModelClient) *TieredRouter {
    return &TieredRouter{tier: clients}
}

// Complete attempts each model in the tier, fail-back on error.
func (r *TieredRouter) Complete(ctx context.Context, prompt string) (string, error) {
    var errs []error
    for _, client := range r.tier {
        resp, err := client.Complete(ctx, prompt)
        if err == nil {
            return resp, nil
        }
        errs = append(errs, fmt.Errorf("%s: %w", client.Name(), err))
    }
    return "", errors.Join(errs...)
}

This is intentionally boring: try the next model in the same tier on failure, return the first success. No retries with backoff yet, no circuit breaker, just the core fail-back idea. In NEXT4I's actual implementation, tiers are populated dynamically and health state feeds back into ordering, but that logic is abstracted here on purpose, the generic version above is what's actually useful to share.

Core Value: Task-Based Routing, the Simple Version

A minimal router that inspects task complexity before picking a tier:

package modelrouter

type Complexity int

const (
    Simple Complexity = iota
    Complex
)

func ClassifyAndRoute(task string, simpleTier, complexTier *TieredRouter) *TieredRouter {
    if estimateComplexity(task) == Simple {
        return simpleTier
    }
    return complexTier
}

func estimateComplexity(task string) Complexity {
    if len(task) < 100 {
        return Simple
    }
    return Complex
}

estimateComplexity can be as crude as a length/keyword heuristic or as sophisticated as a small classifier model, the point is the routing decision happens before the expensive call, not after.

Trade-offs I Made

Fail-back within a tier, not across tiers. Swapping a cheap model in for an expensive one silently would change output quality without anyone noticing. Tiers exist specifically to avoid that.
No cross-request state in the router. Keeps it stateless and trivially horizontally scalable, at the cost of not learning from past failures within a single request lifecycle.
Routing is a toggle, not a mandate. Users can pin a specific model when they need deterministic behavior from one exact provider, the router only kicks in by default.

If there's one thing worth taking away: treat the model as a probability engine you can't fully trust, and let the system around it, fail-back, routing, tool calls for math, carry the reliability burden instead.

Thanks for reading all the way to the end, I'll keep working on more articles like this.

Explore the NEXT4I journey and read the original article at: https://go.next4i.com/next4i/journey/en

How to Build a "Second Brain" with Obsidian That Your AI Agent Can Read, Without Building a Custom RAG Pipeline

NEXT4I DEV — Mon, 17 Aug 2026 11:40:46 +0000

Ever run into this? You wrote a detailed technical spec three months ago, and today someone asks "how did we design this module again?" You end up spending 20 minutes hitting Cmd+F across Google Docs, Trello, and README.md files scattered across different repos, or sometimes there's no documentation at all, so you have to dig through the code and reverse-engineer it by eye.

TLDR; I built a knowledge-base system for NEXT4I using Obsidian (plain Markdown) together with Git and a VS Code AI agent, without writing a single line of custom integration. The core of the system is choosing tools that already "speak the same language" from day one (plain text, open formats), so AI can read our knowledge base practically for free, no RAG pipeline required.

Pain Point: Scattered Knowledge and Requirements Make Search Hard and Nothing Stays in Sync

Before this system, all of NEXT4I's knowledge was scattered across many places: notebooks, Apple Notes, Google Docs, Google Sheets, Trello, README.md files, or, even worse, sometimes there was no documentation at all, just buried in the code, spread across multiple repos each written in a different language, frontend and backend alike.

This isn't just an inconvenience. It makes search genuinely hard, sometimes it's Cmd+F and pray. Worse: my AI coding agent could read the entire codebase, but it had zero visibility into the reasoning behind that code, because that reasoning was scattered somewhere the AI couldn't reach.

Design Constraints: 3 Non-Negotiables

Before picking a tool, I set 3 rules:

It has to be affordable, or free if possible.
It has to be accessible online anytime, from my phone, and still work offline.
Plain text, zero lock-in. If the tool disappears tomorrow, the files must remain immediately readable and usable.
Local-first, Git-friendly. It has to be a normal folder I can git init and track right away.
AI-readable without building extra infrastructure. My AI agent already lives in VS Code, so the knowledge base has to sit inside that workspace without me building an extra pipeline.

Obsidian passed everything, because at its core, an Obsidian vault is just a folder of .md files.

Architecture: Vault Structure

vault/
├── Ideas/          # Raw concepts, brainstorming
├── Manifesto/      # Vision, mission, core policies
├── Principles/     # Design rules, engineering guidelines
├── Infrastructure/ # Deployment topology, IaC specs
├── Platform/       # Domain model, API contracts
├── Script/         # Utility scripts, automation, runbooks
├── Skill/          # Patterns, checklists, reusable knowledge
└── Appendix/       # Domain glossary, citations

Every file is a plain .md. Links use [[wiki-link]] syntax. Metadata lives in YAML frontmatter, and Graph View renders the relationships as a visible dependency graph.

Version control is just git init inside the vault folder, then committing every change with a rationale. git log -- "Infrastructure/sharding-strategy.md" shows the full decision history for that topic. Push it to a private GitHub repo and you get backup, an audit trail, and branching for major revisions, all for free.

Key Insight: AI Access Without Building Anything

This is the part that changed everything.

Obsidian vault = a folder of .md files.
VS Code = opens any folder as a workspace.
AI coding agent (running as a VS Code extension) = reads every file in that workspace.

So the "integration" here is: open the vault folder in VS Code.

That's it. No API, no embedding pipeline, no vector database, no chunking strategy. Just plain Markdown files that the AI agent reads natively.

Prompt Patterns I Actually Use

Contextual search + reasoning:

Search all documents that mention our sharding strategy.
Summarize every trade-off we've considered
and tell me which approach we ultimately chose and why.

Gap analysis:

Look at everything in the Infrastructure/ folder
and tell me which architectural decisions are still undocumented,
compared against the template in Skill/.

Drafting from conventions, not from a blank page:

Using the patterns in Skill/go-backend/ and the domain model in Platform/core/,
draft a design doc for a new message consumer
following our established conventions.

Impact analysis via link traversal:

If I change the authentication rule in Principles/auth.md,
trace every file in Platform/ and Skill/ that links to it via [[links]]
and tell me what needs updating.

The AI reads across multiple files, follows [[wiki-links]], understands the relationships, and synthesizes an answer, without me writing a single line of integration code.

Philosophy: Seamless Integration by Design

The pattern here isn't "integrate 3 tools." It's choosing components that already speak the same language.

Obsidian chose Markdown, the most universally readable format in computing, over a proprietary database. Git works with any plain text. AI agents already know how to read files in a VS Code workspace.

Bonus: Obsidian Canvas as a Visual Layer

Obsidian's Canvas is an infinite whiteboard, place document cards, text, media, then draw connections between them.

I use Canvas for:

System architecture sketches: each service as a card, data flow arrows, real specs embedded right on the board
Decision trees: "if we pick X, then Y and Z are affected," with linked evidence
Plan strategy & flow: for planning work, sequencing, and various NEXT4I workflows

Canvas files are Markdown too under the hood (JSON-like structure), so they're Git-versioned and AI-readable as well. Drop a .canvas file into your VS Code workspace and ask the AI to analyze it for circular dependencies or single points of failure.

What I Learned

What makes this system work isn't the technology, it's what I didn't build. No middleware, no proprietary pipeline, no vendor lock-in.

The discipline of plain text + Git + open formats is a feature, not a limitation.

If you're a dev or a small team drowning in scattered documents, try this before jumping to a heavyweight knowledge-management platform. Plain Markdown with a good folder structure will take you further than you'd expect.

Thanks for reading all the way to the end, I'll keep working on more articles like this.

Explore the NEXT4I journey and read the original article at: https://go.next4i.com/next4i/journey/en

Alternatively, you can register to join NEXT4I the AI-Native Ecosystem I am currently building at: https://go.next4i.com/next4i-devto-en

tags:
#buildinpublic
#secondbrain
#next4i
#obsidian

How I Built an AI-Readable Second Brain with Obsidian, Git, and a VS Code AI Agent

NEXT4I DEV — Fri, 07 Aug 2026 07:55:45 +0000

When you're a solo founder and lead architect, your knowledge base is your most valuable asset. Lose the thread on why a decision was made, and you spend hours — sometimes days — reconstructing context that you already figured out once.

I want to share the exact setup I use at NEXT4I to turn a folder of Markdown files into a fully searchable, version-controlled, AI-readable knowledge system. No proprietary SaaS, no vendor lock-in, no custom integration work.

This is the Key Highlight of this post: a genuinely useful, generic pattern you can apply to your own projects today. The NEXT4I-specific business logic stays abstracted (per our security rules), but the pattern itself is 100% reusable.

1. The Architecture: Three Layers, Zero Magic

┌─────────────────────────────────────────┐
│           AI Agent (VS Code)            │
│   Reads, Searches, Summarizes, Drafts   │
└──────────────────┬──────────────────────┘
                   │ reads plain .md files
┌──────────────────▼──────────────────────┐
│       Git-tracked Obsidian Vault        │
│  ├── Idea/           (brainstorms)      │
│  ├── Infrastructure/ (architecture docs)│
│  ├── Platform/       (product specs)    │
│  ├── Script/         (automation)       │
│  └── Skill/          (reusable limits)  │
└──────────────────┬──────────────────────┘
                   │ committed & pushed
┌──────────────────▼──────────────────────┐
│         GitHub (remote backup)          │
└─────────────────────────────────────────┘

Layer 1 — The Vault (Obsidian): A folder of interconnected .md files. The key insight is that Obsidian uses plain Markdown with [[wiki-links]] for connections — no database, no proprietary format.

Layer 2 — Version Control (Git): Every vault is a git repo. Every change to any document has a commit message, a timestamp, and a diff. You can git log --oneline -- Idea/ to see the evolution of a concept.

Layer 3 — AI Agent (VS Code Extension): Because the vault is just a file tree of .md files, any AI coding agent that can read a codebase can also read your knowledge base. Point the agent at the vault folder, and it has full context.

2. The Setup: Step-by-Step

Step 1: Create the Vault


mkdir next4i-knowledge

cd next4i-knowledge

mkdir Idea Infrastructure Platform Script Skill

git init

Open this folder in Obsidian: Open folder as vault.

Step 2: Link Everything

Inside a note, link to another note with [[Note Name]]. Obsidian auto-suggests as you type. Over time, this builds a graph you can visualize with Cmd/Ctrl + G.

Pro tip: Create a _INDEX.md in each folder that links to the most important notes. This becomes a human-readable table of contents AND a search anchor for the AI.

Step 3: Add Git Discipline


git add -A && git commit -m "infra: initial sharding strategy decision"

git remote add origin git@github.com:your-org/knowledge-vault.git

git push -u origin main

Treat commit messages like code. Use prefixes: idea:, infra:, platform:, script:, skill:. This makes git log --oneline --grep="infra:" instantly useful.

Step 4: Open in VS Code and Activate the AI


code /path/to/vault

With an AI agent extension active (Copilot, Cline, Cody, etc.), try prompts like:

"Summarize the key architectural decisions in the Infrastructure folder."
"Find any contradiction between documents in /Platform/ and /Infrastructure/."
"Draft a new document in /Idea/ based on the sharding notes in /Infrastructure/."

The agent reads the files as context, just like it would for code.

3. The Design Pattern: Folder-Convention-as-API

Here's the key pattern: your folder structure IS your API.

By keeping a consistent vault structure, both humans and AI know where to look:

Folder	Contains	AI Use Case
`Idea/`	Raw, unstructured thinking	Generate summaries, find related concepts
`Infrastructure/`	System topology, deployment, config	Validate consistency, trace dependencies
`Platform/`	Feature specs, user flows	Draft task tickets, check requirement coverage
`Script/`	Automation, one-liners	Explain what a script does, suggest improvements
`Skill/`	Reusable patterns, checklists	Retrieve relevant patterns for new tasks

This is essentially a convention-based RAG (Retrieval-Augmented Generation) setup without any vector database, embedding pipeline, or chunking strategy. The "chunking" is the natural boundary of each .md file. The "retrieval" is the AI agent's file-reading capability.

4. Why This Beats a Wiki

Wiki / Confluence	This Setup (Obsidian + Git)
Vendor lock-in	Plain `.md` files, portable anywhere
Search is siloed within the tool	VS Code AI searches across the whole vault
No version control (or poor built-in)	Full version control (`git blame`, `git diff`, `git log`)
Hard to automate	Scriptable — `grep`, `sed`, and AI prompts all work
AI needs API integration	AI reads files natively, zero setup required

5. What I Learned

The biggest surprise: The AI agent became better at finding connections in my own notes than I was. It doesn't have recency bias. It doesn't forget what I wrote 8 months ago. It reads everything with equal attention.

The biggest lesson: AI-native doesn't mean "add an AI button." It means design your systems — including your thinking systems — so that AI can participate as a first-class citizen without special plumbing.

I'm building NEXT4I as an AI-native ecosystem from the ground up. If you're interested in following a solo founder's engineering journey — or want early access — join here:
Subscribe NEXT4I or want early access — join here

DEV Community: NEXT4I DEV

How to Write an AI Agent Skill File That Reduces Guesswork

The problem with a reasonable instruction

Prompt versus skill

A practical directory structure

A generic SKILL.md example

Before and after

Before

After

Turn the index into a routing table

Single file or multiple files?

Treat skills like software

Validation checklist

Final takeaway

What Is Token & LLM Cost Optimization

What Is a Token in LLMs? A Developer's Guide to Cost Optimization and Architecture

1. What Is a Token Under the Hood?

The Multilingual Token Penalty

2. Formatting Mechanics: Linebreaks & The "Emoji Tax"

3. Input vs. Output Tokens: Why Output Costs 3x–5x More

4. Why Model Pricing Varies by 100x (Dense vs. MoE Architecture)

1. Architectural Design: Dense Models vs. Mixture-of-Experts (MoE)

Dense Models

Mixture-of-Experts (MoE)

The MoE Achilles' Heel: When Routers Fail

🛠️ Engineering Safeguards Used by Frontier Labs:

2. Reasoning Overhead (Thinking / Chain-of-Thought Tokens)

3. Hardware Sovereignty & Custom Silicon

5. 6 Production Strategies to Cut Token Costs by 80%

1. Prompt Engineering for Token Efficiency

2. Leverage Prompt Caching

3. Intelligent Model Cascading (Model Routing)

4. Sliding Context Windows & Conversation Pruning

5. Pre-Retrieval RAG Filtering

6. Multilingual Translation Layer

Key Takeaways

The RAG War Story: How I Learned to Stop Worrying and Love Markdown

The Problem: PDFs Are Pixel-Perfect Hell for AI Parsers

The Generic Pattern: Multi-Path Document Ingestion with Cross-Validation

Architecture

Why Spell-Check is Non-Negotiable for Non-English Languages

The Real Takeaway: Markdown is AI-Native. Everything Else Is Legacy.

Top Destinations

How This Shapes Our Architecture at NEXT4I

What Is LLM Actually Doing? A Fellow Engineer's Take on Vectors, Next-Token Prediction, and Fail-back Routing

The Mental Model: Vectors, Not Meaning

Generation Is Sampling, Not Retrieval

Why LLMs Hallucinate on Arithmetic

Core Value: A Generic Model-Tier Fail-back Router

Core Value: Task-Based Routing, the Simple Version

Trade-offs I Made

How to Build a "Second Brain" with Obsidian That Your AI Agent Can Read, Without Building a Custom RAG Pipeline

Pain Point: Scattered Knowledge and Requirements Make Search Hard and Nothing Stays in Sync

Design Constraints: 3 Non-Negotiables

Architecture: Vault Structure

Key Insight: AI Access Without Building Anything

Prompt Patterns I Actually Use

Philosophy: Seamless Integration by Design

Bonus: Obsidian Canvas as a Visual Layer

What I Learned

How I Built an AI-Readable Second Brain with Obsidian, Git, and a VS Code AI Agent

1. The Architecture: Three Layers, Zero Magic

2. The Setup: Step-by-Step

Step 1: Create the Vault

Step 2: Link Everything

Step 3: Add Git Discipline

Step 4: Open in VS Code and Activate the AI

3. The Design Pattern: Folder-Convention-as-API

4. Why This Beats a Wiki

5. What I Learned

A generic `SKILL.md` example