Skills as a Contract Between AI and Developer
Skills aren't documentation. They're executable contracts — structured knowledge files that tell the AI exactly how your codebase works. Invest two hours writing a skill file, save twenty hours of correcting AI output.
The Premise
Most teams treat AI assistants like search engines: ask a question, get an answer, fix what's wrong. But Logic Bee takes a different approach. Instead of hoping the AI figures out how the code works, we tell it — through .agents/skills/ files that serve as machine-readable contracts between the developer and the AI.
The Story
Before skill files, every AI prompt required extensive context: "By the way, we use naoUtils.mathChain() for math, and naoDateTime() for dates, and errors should use naoFormatErrorById(), and the first thing in the try block should be eventOptions..."
One developer spent 15 minutes adding context to every prompt. Then they extracted it into a skill file — once. Now every AI interaction in the codebase automatically follows those conventions without any prompt engineering.
The return on investment was immediate: fewer review cycles, fewer rejected PRs, and dramatically fewer convention violations in AI-generated code.
What a Skill File Looks Like
# SKILL.md — hook-code-style
---
name: hook-code-style
description: Coding rules, naming patterns, and structural conventions for Logic Bee hooks
---
## Hard Rules (violations = merge blockers)
1. `ok` and `data` must be assigned before `returnEventResult`
2. Every `.flowQuery()` must include `.user(bob.flowUser)`
3. Every write operation must pass `bob.dbSession()`
...
## Soft Conventions (violations = code review comments)
1. `eventOptions` is the first declaration in the try block
2. Use arrow comments: `// -->Get:`, `// -->Set:`
3. Use `naoUtils.mathChain()` for all arithmetic
...
The skill is just a markdown file. But it transforms AI behavior from "best guess" to "informed generation."
What Makes a Good Skill
1. Be Prescriptive, Not Descriptive
❌ "We usually try to use mathChain for calculations"
✅ "ALWAYS use naoUtils.mathChain() for arithmetic. Raw +, -, *, / operators
on financial values are a hard rule violation."
2. Include Examples
Every rule should have a ✅ correct and ❌ incorrect code example. AI learns better from contrast.
3. Separate Hard and Soft Rules
The distinction matters. Hard rules should block generation. Soft rules should trigger warnings.
4. Keep It Focused
One skill per concern. hook-code-style covers coding patterns. flow-query covers database access. Don't mix them.
5. Document the Edge Cases
The 80% cases are obvious. Skills earn their ROI on the 20% that trips up AI:
"When a hook calls bob.runAction(), ALWAYS check the .ok property of the
result before continuing. AI tends to assume sub-requests always succeed."
The Skill Ecosystem
Logic Bee maintains a curated set of skills:
| Skill | Contract |
|---|---|
creating-hooks | File structure, decorator metadata, scaffolding CLI |
bob-request-api | BobRequest accessors and lifecycle |
flow-query | Database operations and tenant scoping |
hook-code-style | Naming, formatting, structural rules |
hook-validation-rules | Hard rules and soft conventions |
event-routing | How events dispatch to hooks |
connectors | External API integration patterns |
interfaces | Type definitions and data factories |
Each skill is a contract: "If you follow these rules, the generated code will be correct."
Measuring ROI
Before and after skill files:
| Metric | Before Skills | After Skills |
|---|---|---|
| AI-generated hooks needing revision | 70% | 15% |
| Convention violations per hook | 3.2 avg | 0.4 avg |
| Time from prompt to merge-ready | 25 min | 8 min |
| Developer context in prompts | 5–10 lines | 1 line (skill reference) |
Writing Your First Skill
Start here:
- Pick your biggest pain point — what does the AI consistently get wrong?
- Write the rule — prescriptive, with examples
- Save it to
.agents/skills/your-skill-name/SKILL.md - Test it — prompt the AI to use the skill and check the output
- Iterate — add rules as you find new patterns the AI misses
The Takeaway
Skills are the highest-leverage investment you can make in AI-assisted development. They turn tribal knowledge into machine-readable contracts. The developer's job isn't to correct AI output — it's to define the rules that make correction unnecessary.
Write the contract once. Get correct code forever.