DEV Community: zerocool

Beyond the Dogma: How Object Calisthenics and AI Taught Me to Write Cleaner Kotlin

zerocool — Fri, 14 Aug 2026 14:22:24 +0000

A story about store layouts, over-engineering, and finding pragmatic balance with an AI Cognitive Sparring Partner.

Act I: The Layout Puzzle

In spatial store design and merchandise engineering, every millimeter in a retail layout matters. Whether you are placing modular shelving, promotional stands, or store fixtures, physical space has strict rules.

In software architecture, our domain models should reflect those same strict rules. Yet, domain logic often ends up scattered across procedural service classes.

A while ago, I was working on our store mapping services—specifically, a feature responsible for calculating the final inventory requirements of furniture fixtures for a seasonal store layout.

I opened the service and found a method responsible for matching fixture families with furniture ranges and aggregating their total quantities. What greeted me was a classic piece of procedural logic:

class StoreFurnitureService {

    fun calculateImplantationFurnitures(
        families: List<Int>,
        implantableElements: List<TreeNodeLeaf>,
        furnitures: List<Furniture>
    ): List<ImplantationFurniture> {
        return families.fold(mutableListOf()) { implantationFurnitures, familyId ->
            val implantedElementDetail = implantableElements.find { it.id == familyId }

            if (implantedElementDetail != null) {
                val furnituresDetail = furnitures.filter { furniture ->
                    furniture.idFamily == implantedElementDetail.id &&
                    implantedElementDetail.rangeChoice.range == furniture.idRange
                }

                furnituresDetail.fold(implantationFurnitures) { allFurnitures, furniture ->
                    val addedFurnitureIndex = allFurnitures.indexOfFirst { it.id == furniture.referenceId }

                    if (addedFurnitureIndex > -1) {
                        val existing = allFurnitures[addedFurnitureIndex]
                        allFurnitures[addedFurnitureIndex] = existing.copy(
                            quantity = existing.quantity + furniture.count
                        )
                    } else {
                        allFurnitures.add(
                            ImplantationFurniture(
                                id = furniture.referenceId,
                                quantity = furniture.count,
                                label = furniture.label
                            )
                        )
                    }
                    allFurnitures
                }
            } else {
                implantationFurnitures
            }
        }
    }
}

Let's pause and pair-program on this snippet for a second. Read lines 16–28 again.

Notice what is happening here?

We have a fold nested inside another fold.
Inside the inner fold, we are searching an accumulator list with indexOfFirst, mutating existing elements in place if found, and appending new ones if not. We are using fold like an imperative loop with state side-effects.
Look closely at the filter condition: implantedElementDetail.rangeChoice.range == furniture.idRange. The service layer is directly reaching three levels deep into a tree node to inspect a raw Int primitive and compare it with another raw Int.

The service is asking objects for their raw data and performing list arithmetic on their behalf. The domain models (Furniture, TreeNodeLeaf) are acting as mere passive data buckets—a textbook example of an Anemic Domain Model violating Tell, Don't Ask and the Law of Demeter.

Act II: Peak Dunning-Kruger (The Over-Engineering Trap)

I wanted to refactor this logic into a clean, rich Kotlin domain model. I remembered Jeff Bay’s 9 rules of Object Calisthenics from The ThoughtWorks Anthology:

Only one level of indentation per method.
Do not use the else keyword.
Wrap all primitives and strings.
First-class collections.
One dot per line (Law of Demeter).
Do not abbreviate.
Keep entities small (under 150 lines).
No class with more than two instance variables.
No getters/setters/properties (Tell, Don't Ask).

"I am going to apply every single rule strictly," I thought.

An hour later, I looked at my changes: I had created 10 separate abstractions—FamilyId, RangeId, FurnitureReferenceId, FurnitureQuantity, FurnitureLabel, FurnitureMatcher, RangeMatchingSpecification, FurnitureAggregationStrategy, and so on.

I had created a maze of single-method wrappers and strategy interfaces just to match a furniture range and add two numbers together. To trace how a single piece of furniture was counted, I had to navigate through layers of abstractions.

I had eliminated the nested branches and wrapped every Int, but I had introduced massive accidental complexity. I had fallen into the Dunning-Kruger trap: confusing dogmatic compliance with good software design.

The Calisthenics Cheat Sheet: From Smell to Idiomatic Kotlin

Object Calisthenics Rule	Procedural Code Smell	Modern Kotlin Solution
Rule 1: 1 Level of Indentation	Deeply nested loops and conditionals	`fold`, `map`, `filter`, and early returns
Rule 2: No `else` Keyword	Branching state machines	Guard clauses (`require`, `check`), `when` expressions
Rule 3: Wrap Primitives	Primitive Obsession (`Int`, `String`)	`@JvmInline value class` (zero-cost allocation)
Rule 4: First-Class Collections	Leaky, mutable `List<T>` operations	Dedicated domain wrapper classes
Rule 9: Tell, Don't Ask	Anemic Data Holders	Rich Domain Entities with behavior methods

Act III: Enter the AI Cognitive Sparring Partner

There are two ways developers use Artificial Intelligence today:

The Viber's Way: Asking AI to "refactor this method using Object Calisthenics." The AI will happily generate 15 files of boilerplate, amplifying your over-engineering and drowning your domain in accidental complexity.
The Craftsman Way: Using AI as a Cognitive Sparring Partner—a concept championed by software craftspeople. You don't ask AI to think for you; you ask it to challenge your design choices and expose your blind spots.

I invoked a custom prompt in my IDE named calisthenics-challenger, pasted my 10 new classes, and asked:

"Play devil's advocate. I strictly applied Object Calisthenics to this furniture aggregation logic. Where did I over-engineer this? Where did I create class explosion instead of domain clarity?"

The AI’s response was an immediate reality check:

"You created FurnitureMatcher, RangeMatchingSpecification, and FurnitureAggregationStrategy. None of these abstractions represent distinct business concepts in your domain—they are procedural logic dressed up in strategy patterns.
In Kotlin, you don't need heavy wrapper objects for every primitive ID. Use @JvmInline value class for zero-cost type safety on FamilyId and RangeId. Then, encapsulate your raw lists into two First-Class Collections: an ImplantedElements collection that knows how to filter by family/range, and an ImplantationInventory collection that owns the accumulation logic via operator overloading."

That pushback changed my perspective. The rules of Object Calisthenics were never meant to be dogmatic laws to follow blindly; they were training wheels designed to build muscle memory around encapsulation and cohesion.

Act IV: The Pragmatic Kotlin Solution

With the AI serving as a guardrail against over-engineering, we refactored the store furniture implantation logic into expressive, idiomatic Kotlin.

Here is the result:

// Rule 3: Zero-allocation Value Objects via Kotlin Inline Classes
@JvmInline
value class FamilyId(val value: Int)

@JvmInline
value class RangeId(val value: Int)

@JvmInline
value class ReferenceId(val value: Int)

@JvmInline
value class Quantity(val count: Int) {
    init {
        require(count >= 0) { "Quantity cannot be negative." }
    }

    // Idiomatic Kotlin operator overloading for domain arithmetic
    operator fun plus(other: Quantity): Quantity = Quantity(this.count + other.count)
}

// Domain Entity encapsulating Furniture characteristics
data class Furniture(
    val referenceId: ReferenceId,
    val familyId: FamilyId,
    val rangeId: RangeId,
    val label: String,
    val count: Quantity
) {
    // Encapsulated domain logic matching range constraints
    fun matchesRange(family: FamilyId, range: RangeId): Boolean =
        this.familyId == family && this.rangeId == range
}

// Rich Value Object representing a matched element in the layout
data class ImplantedElementDetail(
    val id: FamilyId,
    val selectedRange: RangeId
)

// Rule 4: First-Class Collection encapsulating Store Furniture Inventory
class ImplantationInventory private constructor(
    private val items: Map<ReferenceId, ImplantationItem>
) {
    data class ImplantationItem(
        val referenceId: ReferenceId,
        val label: String,
        val quantity: Quantity
    )

    constructor() : this(emptyMap())

    // Immutable collection aggregation using operator overloading
    operator fun plus(furniture: Furniture): ImplantationInventory {
        val existing = items[furniture.referenceId]
        val updatedQuantity = existing?.quantity?.let { it + furniture.count } ?: furniture.count
        val updatedItem = ImplantationItem(furniture.referenceId, furniture.label, updatedQuantity)

        return ImplantationInventory(items + (furniture.referenceId to updatedItem))
    }

    fun toList(): List<ImplantationItem> = items.values.toList()
}

// Rule 4: First-Class Collection managing the Catalog of Furnitures
class FurnitureCatalog(private val furnitures: List<Furniture>) {

    // Rules 1, 2 & 9: Flat processing adhering to Tell, Don't Ask
    fun calculateImplantationRequirements(
        implantedElements: List<ImplantedElementDetail>
    ): ImplantationInventory {
        return implantedElements.fold(ImplantationInventory()) { inventory, element ->
            val matchingFurnitures = furnitures.filter { furniture ->
                furniture.matchesRange(element.id, element.selectedRange)
            }
            matchingFurnitures.fold(inventory) { currentInventory, furniture ->
                currentInventory + furniture
            }
        }
    }
}

Why This Design Works

Zero else Keywords & Single-Level Nesting: The imperative nested loops and list mutations were replaced with immutable functional operations (fold, filter).
First-Class Collection (ImplantationInventory): The logic for merging furniture quantities by ReferenceId no longer lives in a random service method. It is isolated inside ImplantationInventory, which manages its internal map immutably using the + operator.
The Victory of Tell, Don't Ask: Compare these two lines:
Before (Procedural): implantedElementDetail.rangeChoice.range == furniture.idRange
After (Crafted): furniture.matchesRange(element.id, element.selectedRange)
We stopped reaching three levels deep into internal object structures and started delegating intent directly to the entity.
Compile-Time Type Safety: Kotlin's @JvmInline value class ensures we can never accidentally pass a RangeId into a parameter expecting a FamilyId, with zero runtime allocation overhead.

Act V: Your AI Sparring Toolkit (4 Custom Skills)

To integrate this workflow into your daily routine—whether using Claude Code, Cursor, or custom assistant prompts—here are the four AI Skills formatted for your IDE environment.

Skill 1: `calisthenics-suggester`

---
name: calisthenics-suggester
description: Analyzes legacy or complex Kotlin code for Object Calisthenics violations and proposes a clean domain refactoring plan. Use when staring at a complex method, deep nested branches, primitive obsession, or anemic domain logic.
---

## Calisthenics Opportunity Suggester

Identifies structural code smells in Kotlin code using Object Calisthenics as a diagnostic tool, then proposes a pragmatic refactoring strategy.

When exploring the codebase, read `CONTEXT.md` (if it exists) to match domain language.

## Diagnostic Process

1. **Scan for Core Violations:**
* **Indentation & Branching:** Methods with >1 level of nesting or reliance on `else` keywords.
* **Primitive Obsession:** Raw `Int`, `String`, or `Double` types carrying business invariants without validation.
* **Naked Collections:** Direct list manipulation (`filter`, `map`, `reduce`, `indexOfFirst`) inside service classes instead of dedicated containers.
* **Anemic Domain Entities:** Classes that act as passive data buckets while services execute domain math on their behalf (*Tell, Don't Ask* breach).


2. **Formulate Refactoring Strategy:**
* Group raw primitives into Kotlin `@JvmInline value class` abstractions.
* Extract raw collection operations into First-Class Collections.
* Convert nested conditional logic into early-exit guard clauses (`require`, `check`).


3. **Output Format:**
* **Smells Identified:** Quote the exact lines violating encapsulation.
* **Domain Concept to Surface:** Name the hidden business entity or value object wanting to be born.
* **Refactored Kotlin Draft:** Provide concise, high-signal Kotlin code implementing the fix.

Skill 2: `calisthenics-challenger`

---
name: calisthenics-challenger
description: Acts as a pragmatic Tech Lead to challenge proposed refactorings. Prevents over-engineering, class explosion, and YAGNI violations. Use before committing a refactoring or when evaluating if a Calisthenics abstraction is worth the complexity.
---

# Calisthenics Challenger (The Cognitive Sparring Partner)

Prevents dogmatic compliance with Object Calisthenics from turning clean code into over-engineered accidental complexity.

## The Sparring Framework

When presented with a proposed refactoring, audit it against these four anti-patterns before approving:

1. **Class Explosion:** Creating 5+ single-method interfaces, strategy patterns, or wrapper classes for a simple requirement. Use Kotlin's `@JvmInline value class` for zero-allocation type safety instead of heavy wrapper objects.
2. **Speculative Generality (YAGNI):** Adding generic parameters, strategy interfaces, or factory wrappers for "future extensibility" not asked for by the domain.
3. **Anemic Abstractions:** Creating a Value Object that wraps a primitive but contains zero validation logic or domain behavior.
4. **Broken Navigation:** Requiring a developer to jump across 8 different small files to trace a single 20-line feature.

## Response Process

1. **Acknowledge the Intent:** State what the refactoring was trying to solve.
2. **Push Back Explicitly:** Point out exactly where dogmatic rule compliance created noise or class explosion.
3. **Offer the Pragmatic Balance:** Show a simplified Kotlin alternative that retains domain encapsulation without file clutter.

Skill 3: `boyscout-refactor`

---
name: boyscout-refactor
description: Scopes down refactoring after completing a feature or bugfix. Identifies exactly ONE low-risk Object Calisthenics improvement on touched files without expanding scope. Use right after passing feature tests before opening a PR.
---

# Boy Scout Refactor

Applies the Boy Scout Rule (*"Leave the code cleaner than you found it"*) in surgical, low-risk vertical slices.

## Rules of Engagement

1. **Scope Limit:** Examine ONLY files touched in `git diff HEAD~1` or current working tree.
2. **Single Improvement Rule:** Identify and execute **exactly ONE** high-value refactoring. Do not attempt a full system rewrite.
3. **Zero Behavior Change:** The refactoring must preserve existing test coverage. Run tests before and after.

## Priority Checklist (Pick ONE)

* [ ] **Guard Clauses:** Replace a nested `if/else` block with an early `require()` or `check()` guard clause.
* [ ] **First-Class Collection:** Extract a raw list/map filtering pipeline into a dedicated First-Class Collection method.
* [ ] **Value Class:** Convert a naked domain parameter (e.g., `familyId: Int`) into a Kotlin `@JvmInline value class`.
* [ ] **Tell, Don't Ask:** Move a calculation from a service method directly onto the entity holding the data.

Skill 4: `craft-code-review`

---
name: craft-code-review
description: Two-axis code review evaluating diffs along Standards (Object Calisthenics & Kotlin Idioms) and Spec (PRD/Issue requirements). Use during pull request review or before merging work-in-progress.
---

# Craft Code Reviewer

Executes a two-axis review comparing the current diff against **Standards** (Software Craftsmanship / Object Calisthenics) and **Spec** (Issue / Business Requirements).

## Process

1. **Identify Context:** Capture diff via `git diff <fixed-point>...HEAD`. Read `CONTEXT.md` for domain terminology.
2. **Standards Axis:** Evaluate diff against Calisthenics rules (Indentation depth, `else` keyword, primitive obsession, naked collections, *Tell, Don't Ask*, and over-engineering).
3. **Spec Axis:** Verify acceptance criteria, check for missing edge cases or scope creep.

## Output Format

Present findings under separate headings without reranking:

### Standards Findings

* [Rule/Smell Name]: Quote hunk & suggest Kotlin fix.

### Spec Findings

* [Requirement ID/Line]: Missing or incorrectly implemented behavior.

### Summary

* Standards: X findings | Spec: Y findings

Continuous, Intentional Learning

As Robert Heinlein wrote, "When one teaches, two learn."

Software craftsmanship isn't about collecting tools, chasing trendy frameworks, or blindly following 18-year-old rules. It is about understanding the underlying domain problem deeply enough to choose the right trade-offs for that exact context.

When you combine disciplined constraints like Object Calisthenics with modern Kotlin idioms and an AI assistant that actively challenges your design decisions, you stop writing clever code—and start building software that makes tomorrow easier than today.

What are your favorite Object Calisthenics rules to use (or break)?

Stop Vibe-Checking Your AI Agents: The Complete Guide to the SKILL.md Lifecycle

zerocool — Tue, 11 Aug 2026 14:17:28 +0000

Let’s be honest about how most of us build AI skills today.

We sit down, write a few hundred lines of system prompts or instructions, run them once or twice in our local terminal, see that it works, and hit merge. We call it a day. There are no automated tests, no regression suites, and no validation gates.

We pull changes based entirely on a vibe check.

But here is the catch: AI skills are no longer just toys generating poetic text. In modern agentic workflows, your skills are triggering production deployments, drafting legal contracts, bootstrapping infrastructure, and communicating directly with internal databases via your APIs.

When a traditional software function breaks, you get a noisy stack trace. When an AI skill breaks—and it will break the second the underlying model receives a silent upstream update—it fails in absolute silence. It doesn’t crash. It simply hallucinates an answer with unearned confidence, directly to a user who trusts it.

If your AI skills have the power of code, you need to start treating them like code. That means moving from vibes to engineering: design, validation, evaluation, and strict retirement. Let’s take a journey through what it actually takes to run a professional AI skill pipeline.

What an AI Skill Actually Is Under the Hood

Stripped of the marketing hype, an AI skill is remarkably simple: it’s a folder.

At the root of this folder sits a single file: SKILL.md. This file contains a YAML header (known as the frontmatter) followed by a body written in standard Markdown.

The frontmatter tells the agent when to use the skill.
The body tells the agent how to do the work.

---
name: setup_nextjs_app
description: Use this skill when the user wants to bootstrap a new Next.js project with Tailwind CSS.
allowed_tools: [bash, file_writer]
---
# Setup NextJS App
Follow these steps to safely initialize the repository...

This format is a rapidly emerging open standard. Born out of research at Anthropic and open-sourced at agentskills.io, it has been rapidly adopted across the ecosystem by tools like Claude Code, GitHub Copilot, Cursor, Mistral, and Gemini CLI. Think of a SKILL.md file as the package.json of the agentic era.

The magic that keeps this system efficient is an architectural pattern called progressive disclosure. If an agent had to read the full body of every single skill you wrote at the start of every user prompt, your context window would explode. Instead, agents load skills in three distinct waves:

Discovery: The agent scans your repository but only reads the name and description from the YAML frontmatter. This costs a tiny fraction of tokens (around 100 tokens per skill).
Activation: Only when a user’s prompt matches a specific description does the agent open the file and inject the full Markdown body into its context.
Execution: Scripts, templates, and complex environment references are fetched purely on-demand as the steps run.

This architectural reality reveals the number one reason why custom skills fail to trigger: it’s almost never a code problem; it’s a description problem.

Because the agent never looks at the body of the skill during the discovery phase, it relies entirely on the description to route the request. If your description reads like a documentation comment rather than an explicit behavioral trigger, your agent will walk right past it.

The Two Families of Skills

Not all skills are created equal. Understanding how they age dictates exactly how you need to test them. Anthropic separates them into two distinct categories:

1. Capability Uplift Skills

What it does: Teaches the model to do something it cannot do well natively (e.g., parsing a highly specific PDF format or generating a perfectly styled Word document).
Lifespan: Short. Obsolescence comes fast in this category. What a model fails at today might be handled flawlessly and natively by an upstream foundational model update a year from now.
Why it needs evals: To detect obsolescence. Your evaluations will warn you the moment a newer foundation model renders your custom code redundant.

2. Encoded Preference Skills

What it does: It doesn’t teach the model anything fundamentally new—the model already understands every individual step. Instead, it sequences those steps according to your company’s exact business logic or architectural workflow.
Lifespan: Long. These are highly durable. They live as long as your internal business process lives.
Why it needs evals: To verify absolute fidelity to your workflow. You need to ensure the model doesn’t skip a mandatory compliance, security, or logging step over time.

Skip managing this lifecycle, and you will fall victim to skill rot—a slow accumulation of dead folders and conflicting descriptions that pollute your discovery phase and confuse your router.

Phase 1: Designing with Intent

The most common trap is starting with the Markdown body. It feels natural to write out the beautiful, styled steps first, but expert engineering requires the exact inverse.

Write the description first: Treat it like a user prompt. If a developer wanted to invoke this skill explicitly, what would they type? Put those exact keywords into the description.
Expose hidden assumptions: Bugs love the spaces between what the model thinks it knows and what your environment actually expects. Before writing execution code, explicitly state three categories of hypotheses:
Trigger assumptions: What should match, and critically, what should not match?
Environment assumptions: Does this skill assume an empty directory? A specific package manager? Active network access? (Pro tip: always write a step that checks these prerequisites before executing real work).
Execution assumptions: What dependencies must be present? What is the strict sequence of events?
Write the body as explicit directives: Use numbered steps and authoritative vocabulary. “Always use method()” performs exponentially better than “It is recommended to use method()”. LLMs obey directives far better than they synthesize suggestions.

Phase 2: The Human Quality Gate (Validation)

Validation sits right between design and automated evaluation. Think of it as a manual code review checkpoint to see if a skill is clean enough to earn a spot in your test runner.

Before committing, run through this 7-point validation checklist:

Is the frontmatter syntactically complete and accurate?
Does the description read like a routing trigger, not a comment?
Does the body include explicit “when to apply” and “when to ignore” sections?
Is the methodology structurally sound with numbered steps and zero TODO items?
Is the allowed_tools block minimized? (If a skill only reads data, block it from running bash scripts).
Is the exact output format stringently documented?
Does it follow the Single Responsibility Principle? (One skill, one domain).

Phase 3: Writing Targeted Evals

An AI skill “eval” is not a massive, generalized academic benchmark. It is a highly targeted, reproducible unit test. It consists of four elements: a prompt, an agent run execution trace, a suite of checks, and a historical score to track regression over time.

When defining what a “successful run” looks like, you must look across four distinct dimensions:

The Outcome: Did the agent finish the task? Does the generated application actually boot up?
The Process: Did it invoke the correct skill? Did it use the right tools, or did it go rogue?
The Style: Does the code respect your company’s formatting rules, nomenclature, and exact SDK imports?
The Efficiency: Did it achieve the goal optimally?

Efficiency is where invisible cost leaks hide. Two different skills can produce the exact same working code output. But if Skill A takes 3,000 tokens and Skill B takes 12,000 tokens because it repeatedly retried failing bash commands, Skill B represents an invisible architectural regression. You can only catch this by tracking the trace.

Building Your Automated Test Suite

You don’t need thousands of test cases to start. A lean set of 10 to 20 highly diverse prompts is more than enough for a single skill. As users encounter real-world failures, harvest those edge cases and feed them directly into your test suite.

Ensure your test set breaks down into these four core buckets:

Explicit Invocation: The prompt names the skill directly.
Implicit Invocation: The prompt describes a business scenario without mentioning the skill’s name.
Contextual Noise: The prompt wraps the intent in realistic, chaotic developer conversations to test routing durability.
Negative Controls: Prompts designed specifically to see if the skill falsely triggers when it shouldn’t.

Phase 4: The 3-Layer Grading Matrix

Once your tests run, how do you grade the output programmatically? You build a tiered grading structure.

Layer 1: Deterministic Graders

These are your unit tests. They are fast, completely reproducible, and dirt cheap. They read the JSON execution trace or the disk artifacts and evaluate binary realities:

Did the agent write a package.json to the disk?
Did the code import the correct SDK version?
Did it call the new method instead of the deprecated one?

This layer is usually written in a few dozen lines of Python or TypeScript using simple regex, file checking, or AST parsing. If a check can be written deterministically, it must be written deterministically.

Layer 2: LLM-as-a-Judge

Deterministic code can tell you if a file exists, but it cannot tell you if the architectural trade-offs inside that file make sense. For qualitative assessment, we use a secondary LLM as an impartial judge, scoring the output against a highly granular grading rubric.

To ensure your system can parse the evaluations automatically, enforce a strict JSON schema layout for your rubrics:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "JSON Rubric for Deterministic Checks",
  "type": "object",
  "properties": {
    "overall_pass": { "type": "boolean" },
    "score": { "type": "integer", "minimum": 0, "maximum": 100 },
    "checks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "pass": { "type": "boolean" },
          "notes": { "type": "string" }
        },
        "required": ["id", "pass", "notes"],
        "additionalProperties": false
      }
    }
  },
  "required": ["overall_pass", "score", "checks"],
  "additionalProperties": false
}

When building an LLM judge, you must enforce two non-negotiable rules:

Enforce a strict JSON schema output so you can programmatically track scores over time in your CI pipeline.
Run the judge 3 to 5 times per test and evaluate the score distribution. Because the judge itself is an LLM, its grading has a variance curve. Tighten your rubrics to minimize this drift.

Layer 3: Advanced Environment Runtime Checks

The ultimate layer of confidence mimics a real production environment:

Run a static analysis build check (npm run build or mvn compile) to catch broken imports.
Run git status --porcelain to ensure the agent left a clean workspace.
Spin up the containerized app and ping it with an automated curl request to verify a 200 OK response.

Phase 5: Spotting “Outgrowth” and Retiring Skills

Most teams are fantastic at creating skills, but terrible at deleting them. Over time, your codebase gets bloated with legacy instructions. Automated evals give you the exact instrument you need to clean house via two specific patterns:

Catch Regressions: Your skill worked perfectly a month ago. The model provider ships a stealth update, and suddenly the skill begins looping or failing. Scheduled CI evals will instantly sound the alarm before your users find out.
Spot Outgrowth: You wrote a complex Capability Uplift skill in 2025 to help a model parse intricate markdown tables. By 2026, the native foundational model has improved so much that it can do this out of the box.

How do you test for outgrowth? Run your eval suite with the skill completely turned off. If the agent passes your rigorous tests without the extra instructions, the model has absorbed the capability natively. Your skill is officially dead weight. Move it to an archive/ folder, log the retirement date, and delete it.

Shift from How to What: The “Skills as Code” Matrix

If we peel back the AI hype and look at the structural design of a SKILL.md setup, it becomes undeniable: AI skills are code.

Let’s look at this direct architectural mapping as a clean side-by-side alignment:

The YAML Description ➔ Your Public API Contract (It handles discovery and routing).
The Markdown Body ➔ Your Implementation Details (The sequential instructions).
The Allowed Tools ➔ Your Core Dependencies (Filesystem, bash, or API permissions).
Automated Evals ➔ Your Unit & Integration Tests (The absolute guardrails of success).

The Evolution of the Body

Right now, a SKILL.md file is an imperative implementation plan. It explicitly holds the model’s hand, telling it what to do step-by-step.

But look closely at what a robust evaluation suite actually contains. It holds target prompts, expected file artifacts, explicit formatting conventions, and token efficiency budgets. Your evals already describe the what—while remaining entirely silent on the how.

In traditional software history, every time an industry transitions from telling the machine how to do something to simply telling it what we want achieved, engineering capabilities skyrocket and friction drops. We saw it when manual imperative scripts gave way to declarative infrastructure (like Terraform or Kubernetes), and we saw it when hand-crafted loop indexing gave way to SQL query planners.

As foundational LLMs continue to become more capable, the imperative Markdown body of your custom skills is going to shrink. Models will already inherently know how to safely execute standard engineering workflows. Legacy capability uplift instructions will vanish entirely. Your business-specific preference skills will reduce down to a single paragraph of pure intent, a few gold-standard examples, and a rigorous test set asserting your company’s constraints.

The code inside the skill body is temporary. The evaluation contract is permanent.

Today, your evals verify your skills. Tomorrow, the eval could be the skill. The description of success will become so precise that a highly capable model will simply deduce the implementation path dynamically at runtime.

Writing strict, automated e-vals today isn’t just a defensive quality-assurance practice to keep your current agents from breaking next week—it is a long-term architectural investment.

Stop guessing if your AI agents actually work. Build your contracts, establish your baselines, and start measuring.

Sources & Further Reading

To dive deeper into the AI agent skill lifecycle, engineering workflows, and evaluation strategies, explore these official open standards and research papers:

[Anthropic Claude Blog] Improving Skill Creator: Test, Measure, and Refine Agent Skills – The foundational framework detailing how to refine custom agent capabilities.
[OpenAI Developers] Eval Skills & Agentic Frameworks – OpenAI’s perspective on standardizing evaluations within enterprise-grade agent layers.
[Philipp Schmid] Testing AI Agent Skills in Production – A hands-on, practical technical guide on building and deploying automated test runners for LLM actions.
[ArXiv Research] Evaluation and Lifecycles of Agentic Skills – The core academic research paper breaking down token consumption patterns, skill drift, and model outgrowth.
[Ultimate Claude Code Guide by Bruniaux] Learning Path: Skill Lifecycle & Open Standards – An extensive deep-dive into the mechanics of the open SKILL.md format and the architecture of progressive disclosure.
[Anthropic Developer Docs] Using the Evaluation Tool in Console – The step-by-step user manual for configuring matrix test sets and scoring model responses quantitatively.
[GitHub Awesome-Copilot] Official agentic-eval Skill Standard – The gold-standard open-source reference template implementing automated self-critique loops and JSON-structured rubrics.

The Go Era: What Actually Matters in TypeScript 7.0 (Beyond the 10x Speedup)

zerocool — Fri, 17 Jul 2026 09:22:03 +0000

The tech world has spent the last year buzzing about the complete rewrite of the TypeScript compiler. Now that TypeScript 7.0 is officially out, the headline is clear: a native Go port delivering 8x to 12x build speedups and an instant editor experience.

But if we look past the raw performance numbers, TypeScript 7.0 represents something much deeper. It is the most aggressive modernization sweep in the language's history. The TypeScript team used this architectural migration to eliminate a decade of technical debt, kill off legacy web standards, and restructure how the compiler interacts with the JavaScript ecosystem.

If you are planning to upgrade your frontend or backend repositories, here is what actually matters, why the team chose Go, and the breaking changes you need to prepare for.

1. The Architectural Plot Twist: Why Go and Not Rust?

When Microsoft first announced they were moving away from a bootstrapped JavaScript compiler to a native binary, the collective internet assumed they would choose Rust—the darling of the modern frontend tooling space (used by SWC, Turbo, and Oxc).

Instead, the team chose Go, sparking heavy debate across the community. The reasoning reveals exactly how the TS team prioritizes stability over absolute micro-benchmarks:

Bug-for-Bug Compatibility: The goal wasn't to write a brand-new compiler from scratch; it was a 1:1 faithful translation of the massive, decade-old TypeScript codebase. Go’s straightforward syntax allowed a clean mapping of existing JavaScript logic.
The Memory Model Challenge: Compilers are inherently full of deeply nested, circular object graphs (ASTs, symbol tables, type structures). Managing these in Rust without heavily leaning on unsafe blocks or running into a brick wall with the borrow checker would have taken years.
Garbage Collection Alignment: Go’s built-in garbage collection mirrors JavaScript’s memory model elegantly. This allowed the team to achieve multi-threaded parallelism safely and ship a stable production compiler years faster than a Rust rewrite would have allowed.

2. The Great Modernization Sweep (The Real Breaking Changes)

TypeScript 7.0 acts as a strict forcing function to push the entire ecosystem into the modern era. If your repository relies on configurations or patterns from five years ago, TS 7.0 will throw hard compilation errors instead of warnings.

The Death of Legacy Formats

Goodbye ES5: The ES5 output target is officially dead. TypeScript 7.0 defaults its target to the current stable ECMAScript version preceding esnext. If you still need to support legacy browsers that don't support ES6 classes, you must handle down-leveling via an external bundler or babel step.
Legacy Modules Prohibited: Support for legacy module systems (AMD, UMD, and SystemJS) has been completely discontinued.
The Elimination of downlevelIteration: Iteration helpers for ancient targets have been stripped out.

Strict Configuration Defaults

strict is True by Default: You no longer opt-in to strict type-checking; it is the default baseline behavior for any new initialization.
module Defaults to esnext: This ensures modern bundlers (Vite, Rsbuild, etc.) receive standard ESM out of the box.

Path Resolution Adjustments

baseUrl is Dead: You can no longer use baseUrl for absolute path mappings. TypeScript 7.0 strictly requires you to use the modern paths property for aliases.
rootDir Restrictions: rootDir now defaults to ./. If your tsconfig.json sits in your root folder but your source code is inside a /src directory, you must explicitly define "rootDir": "./src". Failing to do so will alter your build's output directory layout.
Global types are Isolated: Previously, TypeScript would automatically scan your entire node_modules/@types folder and inject them globally. TS 7.0 defaults the types array to [] (empty). If your backend relies on Node global variables (like process.env) or your frontend relies on browser testing globals, you must list them explicitly (e.g., "types": ["node"]).

Modern ECMAScript Realignment

Import Assertions Banned: The legacy assert { type: "json" } syntax has been completely dropped. You must use the official ECMAScript standard: with { type: "json" }.
The module Namespace Fix: You can no longer use the module keyword to declare code namespaces (e.g., module MyNamespace {}). You must use the namespace keyword exclusively.

3. The Language Fix: Unicode-Aware Types

While the core type-checking logic is structurally identical to previous versions, there is a major language fix under the hood involving template literal types.

In older versions of TypeScript, string manipulation at the type level could easily break when encountering surrogate pairs, emojis, or specific international characters. TypeScript 7.0 correctly preserves Unicode code points during type inference. If your project does heavy string-manipulation types (such as routing schemas, internationalization keys, or database ORM typings involving special characters), types will no longer mysteriously break when facing an emoji.

4. Rebuilt File Watching

If you spend your day running tsc --watch, TypeScript 7.0 introduces an entirely new filesystem watcher. Rather than relying on computationally heavy polling mechanisms that slow down dramatically when dealing with giant node_modules folders, the team successfully ported the core logic of the highly efficient Parcel file-watcher (@parcel/watcher) directly into Go.

The result is a drastically lower CPU and memory footprint on your machine while watch-mode sits in the background of your local frontend and backend servers.

5. Your Biggest Immediate Headache: The Missing JS API

There is one massive catch you need to look out for if you upgrade today: TypeScript 7.0 does not ship with a programmatic JavaScript API.

Because the entire compiler engine was moved to Go, JavaScript-based tools cannot import and execute compiler methods natively yet. This affects critical tools in your toolchain—most notably typescript-eslint, along with various framework-specific compiler extensions (like those for Vue or Svelte templates).

To prevent the ecosystem from shattering, Microsoft has introduced a bridging strategy. If you want to use TS 7.0 for your builds but still need your linter to function, you have to run a dual-installation using npm aliases:

{
  "devDependencies": {
    "typescript": "npm:@typescript/typescript6@^6.0.2",
    "@typescript/native": "npm:typescript@^7.0.2"
  }
}

This ensures that your development tools can fall back to the JavaScript-based TypeScript 6.0 API, while your actual code compilation uses the native Go-based tsc runner. The TypeScript team promises a brand-new native programmatic API will arrive with TypeScript 7.1 in a few months to resolve this permanently.

The Verdict

TypeScript 7.0 is far more than a performance patch. It represents Microsoft drawing a line in the sand and leaving the legacy web behind. By shedding ES5 targets, killing dead module frameworks, and tightening configuration defaults, it delivers a sleeker, faster, and remarkably modern toolchain.

If your codebase is already aligned with modern ESM standards, the upgrade will feel like an absolute gift to your daily developer workflow. If you are harboring legacy tech debt, TS 7.0 is the wake-up call to finally clean it up.