Skills: Judgment as Documents

Every business runs on judgment. Not the judgment you find in a policy manual or a flowchart, the judgment that lives in the heads of your best people. The sales lead who knows which prospects are real. The ops manager who knows when to escalate. The account exec who knows which clients need a phone call instead of an email.

That judgment is the most valuable thing in your organization, and right now it’s trapped. It walks out the door every evening and you hope it comes back Monday morning.

Skills-as-Documents is how you set it free.

The Skills-as-Documents Paradigm

A skill is a structured markdown document that encodes domain expertise in a format both humans can review and AI agents can execute. Instead of code or prompts, a document that captures the “it depends” decisions that make businesses run.

This is the core insight of Business-as-Code: business expertise can be written down in a structured way that preserves the judgment, the exceptions, the context-dependent reasoning that makes an expert an expert. And once it’s written down, an AI agent can read it and act on it.

Traditional automation forces a binary choice. Either you write rigid code that handles the happy path and breaks on exceptions, or you write documentation that humans read and interpret (when they remember to read it at all). Skills occupy the space between these two extremes.

A skill tells an agent: here’s how we think about this problem. Here are the criteria. Here are the weights. Here are the exceptions. Now apply judgment.

The agent doesn’t execute the skill like a script. It reads the skill like a knowledgeable colleague reads a briefing document, understanding the intent, applying the criteria, handling edge cases that the document didn’t explicitly anticipate because it provided enough context for good judgment.

This matters because the alternative is what most organizations do: spend months trying to codify business rules into deterministic systems, watch those systems fail on the first edge case, then fall back to “just have a person do it.” Skills break that cycle. They’re fast to write (hours, not weeks), fast to iterate (edit a document, not refactor a codebase), and they handle ambiguity by design.

NimbleBrain maintains a skills library in packages/skills/, real skills that our own agents use daily. Proposal generation. Code review. Client onboarding. Each one is a markdown document. Each one encodes judgment that used to live in a single person’s head. That’s Context Engineering in practice: structuring organizational knowledge so any AI agent can operate on it.

Anatomy of a Skill

A skill follows a consistent structure. Here’s a real example: a lead qualification skill that encodes the judgment a senior sales rep applies to every inbound lead:

# Lead Qualification Skill

## Purpose
Evaluate incoming leads and assign a qualification score (1-100).

## Inputs
- Lead company name, industry, size
- Lead source (inbound, referral, outbound)
- Stated pain point

## Criteria
- Company size 50-500 employees: +20 points
- Industry in [SaaS, fintech, healthcare, manufacturing]: +15 points
- Inbound source: +25 points, Referral: +30 points
- Pain point mentions "AI", "automation", or "agents": +20 points
- Has existing AI investment: +10 points

## Decision Rules
- Score >= 70: HOT, route to founder for immediate outreach
- Score 40-69: WARM, add to nurture sequence
- Score < 40: COLD, add to newsletter only

## Exceptions
- Any company > 500 employees: always HOT regardless of score
- Any referral from existing client: always HOT

Each section serves a specific purpose:

Purpose defines the scope. One skill, one job. “Evaluate incoming leads,” not “manage the entire sales pipeline.” Tight scope means the agent knows exactly what it’s responsible for and when to hand off.

Inputs declare what data the agent needs before it can act. This is the skill’s interface to the outside world. An agent reading this skill knows it needs company size, industry, source, and pain point before it can produce a result. No guessing, no hallucinating context.

Criteria encode the scoring logic: the weighted factors an expert considers. Notice these aren’t hidden in code. A sales director can read these criteria, disagree with the weights, and change them in five minutes. Try doing that with a scoring algorithm buried in your CRM’s custom code.

Decision Rules map scores to actions. This is where the skill connects evaluation to execution. The agent doesn’t just produce a number; it knows what to do with that number.

Exceptions are where skills earn their keep. In rigid code, exceptions are bugs waiting to happen, special cases handled by nested conditionals that accumulate until the system is unmaintainable. In a skill, exceptions are first-class citizens. They’re written in plain language. They override the rules when the situation demands it. The agent reads “any referral from existing client: always HOT” and applies that override with the same fluency a human would.

Skills vs. Prompts vs. Code

Three ways to give instructions to an AI system. Each has a place. Most organizations conflate them and get worse results from all three.

	Prompt	Skill	Code
Lifespan	One-shot	Persistent	Persistent
Readability	Human	Human + AI	Developer only
Judgment	None	Yes	No
Versioning	No	Git	Git
Testing	Ad hoc	Scenario-based	Unit tests
Who edits	Anyone	Business + eng	Engineers only

A prompt is an instruction for a single interaction. “Summarize this email.” “Draft a response to this complaint.” Prompts are ephemeral. They serve one moment and disappear. They don’t accumulate. They don’t compound. You can’t version-control a prompt because it was never meant to persist.

A skill is a persistent document that encodes reusable expertise. It lives in your repository. It gets reviewed, versioned, tested against scenarios. When a skill changes, you can see the diff, understand why, and trace the impact. Skills are assets that appreciate over time as you refine them against real-world edge cases.

Code is deterministic logic. It does exactly what it’s told, every time, with no interpretation. Code is the right tool when you need precision and repeatability: data transformations, API integrations, mathematical calculations. But code can’t handle ambiguity. It can’t exercise judgment. And it requires an engineer to modify.

The failure mode most organizations hit: they try to encode judgment as code. They build sprawling rule engines with hundreds of conditional branches, then wonder why the system is brittle, expensive to maintain, and wrong 30% of the time. Skills handle that 30% because they give the agent room to interpret, weigh, and decide.

When to Use Skills vs. Code

The dividing line is judgment.

If the task requires weighing competing factors, handling exceptions, or making context-dependent decisions, write a skill. Lead qualification. Content review. Escalation triage. Vendor evaluation. These are judgment-heavy processes where the “right answer” depends on context, and an expert would say “it depends” before answering.

If the task is purely mechanical (deterministic, repeatable, and performance-critical) write code. Data validation against a schema. API request formatting. Mathematical calculations. CSV parsing. These are engineering problems with engineering solutions. No judgment required.

If a business expert needs to understand and modify the logic, it’s a skill. If only engineers need to touch it, code is fine.

The hybrid pattern works well in practice: code handles the plumbing (fetch the data, format the output, call the API), and skills handle the reasoning (decide what to do with the data, evaluate the situation, choose the next action). NimbleBrain builds systems this way: the infrastructure is code, the intelligence is skills.

One more heuristic: if you find yourself writing comments in code that explain the “why” behind business logic, that logic probably belongs in a skill instead. Comments decay. Skills are maintained.

Writing Effective Skills

Five principles that separate skills that work from skills that waste tokens.

Be specific, not aspirational. “Evaluate the lead” is a prompt. “Score the lead against these five weighted criteria and route based on thresholds” is a skill. Every skill should contain enough detail that two different agents, reading the same skill, would produce materially similar outputs on the same input. Specificity is the difference between delegation and abdication.

Encode the exceptions. The happy path is easy. Anyone can write a skill that handles the obvious case. The value is in the exceptions: the overrides, the special cases, the “unless” clauses that separate an expert from a novice. When you’re writing a skill, ask: “What would a senior person do differently than a junior person?” That difference is your exceptions section.

Provide examples of correct decisions. Abstract criteria produce abstract results. Include two or three examples of real inputs and the expected output. “Company: Acme Corp, 200 employees, SaaS, inbound, mentions automation. Score: 80, route: HOT.” Examples anchor the agent’s interpretation and catch drift before it compounds.

Test against real scenarios. Run the agent with the skill on inputs where you know the right answer. Did it match expert judgment? Where did it diverge? Those divergence points are your iteration targets. Skills improve through contact with reality, not through longer documents.

Iterate based on agent performance, not theory. After the first version ships, watch how the agent applies the skill in production. You’ll find gaps: scenarios the skill doesn’t cover, criteria that need recalibrating, exceptions you forgot. Update the skill. Commit the change. That diff is a record of organizational learning, visible, reviewable, and permanent. This is the Recursive Loop in action: build the skill, operate with it, learn from the gaps, build it better.

Skills are how you stop losing institutional knowledge to turnover, vacation, and the limits of human memory. They’re how you scale judgment without scaling headcount. And because they’re markdown documents in a git repository, they’re the most auditable, reviewable, and improvable form of business logic you can build.

Write one this week. Pick the decision your team makes most often. Write it down. Give it to an agent. See what happens.