A coding agent skill is not a substitute for business context

Ask a coding agent to build a revenue model in dbt and it may do everything you want from an engineering perspective. It can inspect the project, establish output grain, write modular SQL, add tests, run the model, and check its work.

Then it reaches a decision point, where no amount of dbt competence can promise accurate answers: should revenue be recognized on invoice date, shipment date, posting date, or another business event?

My colleague tried this experiment across dbt Wizard and Snowflake CoCo with similar results each time. Coding agents are good, but not good enough to understand business context unless steered towards the right interpretations.

And then there are skills. While a skill can make the agent better at the work, it still doesn’t tell the agent what your company means by revenue. Sometimes, that knowledge just isn’t easily captured or resolved.

Data teams can package engineering practices into reusable agent skills that can make coding agents more systematic, but ultimately data pipeline correctness depends on another category of business context: a spec outlining logic that defines how to build.

Skills give agents coding best practices, but not company-specific context

Anthropic describes Agent Skills as folders of instructions, scripts, and resources that an agent can load when a task calls for them. They let teams package procedural knowledge once and reuse it across sessions.

dbt Labs' first-party analytics engineering skill is a good example of a skill for a coding agent specifically for data pipelines. It tells an agent to follow dbt modeling practices, read model documentation before changing existing models, use ref() and source() instead of hardcoded table names, inspect data with dbt show, and more.

These skills improve how the agent codes and gets it past applying generic solutions to your problem. But agents still need answers to questions such as:

• Which source system is authoritative for a customer attribute?
• Which date assigns a transaction to a reporting period?
• What result should the finished model reconcile against?

The hardest build decisions lie in business requirements

Many decisions that determine whether a data pipeline is correct sit outside the codebase. A few other challenges only business context can solve:

• Grain: an agent may be capable of building at invoice-line grain, but the desired output could be shipment-line grain because partial shipments need to land in separate reporting periods.
• Time semantics: a transaction may have an order date, ship date, invoice date, posting date, close date, and correction date. Choosing one or another changes the business meaning of the model.
• Exclusions, mappings, exceptions, and validation targets: internal transfers may be excluded from one inventory view and included in another. A finance model may be acceptable only if quarter-end revenue reconciles to the close report within an agreed tolerance.

These are requirements for this build, in this organization, for this use case. Treating them as generic agent behavior hides decisions that need to stay explicit. As I argued in the semi-jokingly titled Before you work with a coding agent, talk to Robert, schemas and code can expose the records available to an agent without supplying the business meaning behind them.

Putting every business rule into a skill creates the wrong abstraction

I’d argue that business context doesn’t really belong inside a skill, or in any other instructions file telling a coding agent how to work. There’s a better place for the decisions, definitions, mappings, exceptions, and validation criteria that describe how a specific business works: a spec.

You can create a spec for every build manually by interviewing stakeholders, working through the documents they rely on, resolving gaps, and compiling the decisions the build depends on. Such decisions should be documented explicitly and specific to the build, rather than getting folded into reusable agent instructions.

Some stable domain knowledge belongs in a skill. For example:

When modeling inventory availability, establish the grain and identify how reserved, allocated, damaged, and quarantined quantities are represented before calculating the final measure.

This is reusable guidance about how the agent should work. A rule such as "quarantined inventory never counts as available inventory" meanwhile may hold for one business unit, reporting purpose, or effective period and fail in another.

Encoding build-specific requirements as global agent instructions creates engineering problems

The rule becomes harder to tie to an owner, approval, source, or effective date. It can leak into tasks where it doesn’t apply, and conflicting stakeholder definitions become awkward to represent. A business change now requires changing the agent's general behavior instead of updating the affected requirement.

Traceability suffers too. When someone asks why a transformation excludes a class of transactions, the useful answer is the approved requirement behind it, rather than "the agent's skill told it to."

TL;DR: spec your data pipeline before AI builds.

A spec gives your coding agent a build-specific definition of correct

A spec carries the business requirements crucial to an accurate data pipeline. It gives the coding agent context, and corresponding targets for end state, that skills alone don’t provide.

A spec can preserve who approved business decisions, when they take effect, what evidence supports them, and how the finished data pipeline should be checked.

Skills and specs solve different parts of the same coding agent handoff

A mature agentic data engineering workflow benefits from both skills and specs.

Skills can tell the agent to read the specification before implementation, generate tests from validation criteria, and surface contradictions instead of choosing silently.

The spec then supplies the decisions for this build:

Use posted invoice lines as the revenue grain. Exclude intercompany transactions. Translate using the approved monthly FX rate. Reconcile revenue to the Finance close report within the accepted tolerance.

Now the agent has procedural guidance and an explicit target.

A skill can also teach the agent how to consume a specification consistently: where to find requirements, how to map them to models, and how to turn validation criteria into tests.

Maxa Autopilot Spec is designed for that handoff. It turns business requirements from meeting transcripts, dashboard screenshots, documents, spreadsheets, and systems of record into a structured specification that a coding agent can build against, while flagging unresolved or conflicting decisions.

Proof that passing dbt tests is still different from understanding business context

Good agent skills can improve performance, but the evidence supports being precise about what they improve.

SkillsBench, a 2026 benchmark covering 86 tasks across 11 domains:

• Curated skills increased average pass rate by +16 percentage points
• Results varied substantially by task
• Some tasks performed worse with a skill

dbt Labs takes a similar empirical approach. Its agent-skills repository includes evaluation tooling for comparing skill sets against the same scenario and grading the results.

Even a perfectly functioning skill leaves the business requirement problem untouched.

A data pipeline can compile successfully, follow project conventions, and look reasonable in code review while calculating the wrong business number. Previous Maxa testing with dbt Wizard showed the same distinction: both runs produced clean, conventional dbt projects, while the business requirements in the spec materially changed what the resulting data pipeline could answer and validate.

Review therefore needs two layers:

1. Did the agent execute the engineering workflow correctly?
2. Did the implementation match the intended business decision?

For the second question, use a spec to ensure the coding agent uses the intended source of truth, implements the approved definition, and reconciles to the expected result. Each check should be traceable to the requirement that justified it.

Autopilot Spec generates the spec that lets you do all of this systematically rather than spending weeks building it yourself.

Give your data coding agent a playbook and a spec

Agent skills give data teams a practical way to package good engineering practices and reuse them across coding-agent sessions.

A data pipeline still needs build-specific business context, and a spec provides your data coding agent just that.

As coding agents get better at implementation, leaning on both skills and specs makes it easier to build data pipelines that are accurate and easier to test and maintain.