1"use strict";(self.webpackChunklogic_bee_github_io=self.webpackChunklogic_bee_github_io||[]).push([["2691"],{6352(e,t,s){s.r(t),s.d(t,{assets:()=>a,contentTitle:()=>o,default:()=>h,frontMatter:()=>l,metadata:()=>n,toc:()=>d});var n=s(8764),i=s(1987),r=s(9844);let l={slug:"skills-as-a-contract",title:"Skills as a Contract Between AI and Developer",authors:["gabriel"],tags:["ai","architecture","developer-experience"]},o,a={authorsImageUrls:[void 0]},d=[{value:"The Premise",id:"the-premise",level:2},{value:"The Story",id:"the-story",level:2},{value:"What a Skill File Looks Like",id:"what-a-skill-file-looks-like",level:2},{value:"What Makes a Good Skill",id:"what-makes-a-good-skill",level:2},{value:"1. Be Prescriptive, Not Descriptive",id:"1-be-prescriptive-not-descriptive",level:3},{value:"2. Include Examples",id:"2-include-examples",level:3},{value:"3. Separate Hard and Soft Rules",id:"3-separate-hard-and-soft-rules",level:3},{value:"4. Keep It Focused",id:"4-keep-it-focused",level:3},{value:"5. Document the Edge Cases",id:"5-document-the-edge-cases",level:3},{value:"The Skill Ecosystem",id:"the-skill-ecosystem",level:2},{value:"Measuring ROI",id:"measuring-roi",level:2},{value:"Writing Your First Skill",id:"writing-your-first-skill",level:2},{value:"The Takeaway",id:"the-takeaway",level:2}];function c(e){let t={code:"code",em:"em",h2:"h2",h3:"h3",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",...(0,r.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(t.p,{children:"Skills aren't documentation. They're executable contracts \u2014 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."}),"\n",(0,i.jsx)(t.h2,{id:"the-premise",children:"The Premise"}),"\n",(0,i.jsxs)(t.p,{children:["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 ",(0,i.jsx)(t.em,{children:"tell it"})," \u2014 through ",(0,i.jsx)(t.code,{children:".agents/skills/"})," files that serve as machine-readable contracts between the developer and the AI."]}),"\n",(0,i.jsx)(t.h2,{id:"the-story",children:"The Story"}),"\n",(0,i.jsxs)(t.p,{children:['Before skill files, every AI prompt required extensive context: "By the way, we use ',(0,i.jsx)(t.code,{children:"naoUtils.mathChain()"})," for math, and ",(0,i.jsx)(t.code,{children:"naoDateTime()"})," for dates, and errors should use ",(0,i.jsx)(t.code,{children:"naoFormatErrorById()"}),", and the first thing in the try block should be ",(0,i.jsx)(t.code,{children:"eventOptions"}),'..."']}),"\n",(0,i.jsx)(t.p,{children:"One developer spent 15 minutes adding context to every prompt. Then they extracted it into a skill file \u2014 once. Now every AI interaction in the codebase automatically follows those conventions without any prompt engineering."}),"\n",(0,i.jsx)(t.p,{children:"The return on investment was immediate: fewer review cycles, fewer rejected PRs, and dramatically fewer convention violations in AI-generated code."}),"\n",(0,i.jsx)(t.h2,{id:"what-a-skill-file-looks-like",children:"What a Skill File Looks Like"}),"\n",(0,i.jsx)(t.pre,{children:(0,i.jsx)(t.code,{className:"language-markdown",children:"# SKILL.md \u2014 hook-code-style\n\n---\nname: hook-code-style\ndescription: Coding rules, naming patterns, and structural conventions for Logic Bee hooks\n---\n\n## Hard Rules (violations = merge blockers)\n\n1. `ok` and `data` must be assigned before `returnEventResult`\n2. Every `.flowQuery()` must include `.user(bob.flowUser)`\n3. Every write operation must pass `bob.dbSession()`\n...\n\n## Soft Conventions (violations = code review comments)\n\n1. `eventOptions` is the first declaration in the try block\n2. Use arrow comments: `// --\x3eGet:`, `// --\x3eSet:`\n3. Use `naoUtils.mathChain()` for all arithmetic\n...\n"})}),"\n",(0,i.jsx)(t.p,{children:'The skill is just a markdown file. But it transforms AI behavior from "best guess" to "informed generation."'}),"\n",(0,i.jsx)(t.h2,{id:"what-makes-a-good-skill",children:"What Makes a Good Skill"}),"\n",(0,i.jsx)(t.h3,{id:"1-be-prescriptive-not-descriptive",children:"1. Be Prescriptive, Not Descriptive"}),"\n",(0,i.jsx)(t.pre,{children:(0,i.jsx)(t.code,{children:'\u274C "We usually try to use mathChain for calculations"\n\u2705 "ALWAYS use naoUtils.mathChain() for arithmetic. Raw +, -, *, / operators \n on financial values are a hard rule violation."\n'})}),"\n",(0,i.jsx)(t.h3,{id:"2-include-examples",children:"2. Include Examples"}),"\n",(0,i.jsx)(t.p,{children:"Every rule should have a \u2705 correct and \u274C incorrect code example. AI learns better from contrast."}),"\n",(0,i.jsx)(t.h3,{id:"3-separate-hard-and-soft-rules",children:"3. Separate Hard and Soft Rules"}),"\n",(0,i.jsx)(t.p,{children:"The distinction matters. Hard rules should block generation. Soft rules should trigger warnings."}),"\n",(0,i.jsx)(t.h3,{id:"4-keep-it-focused",children:"4. Keep It Focused"}),"\n",(0,i.jsxs)(t.p,{children:["One skill per concern. ",(0,i.jsx)(t.code,{children:"hook-code-style"})," covers coding patterns. ",(0,i.jsx)(t.code,{children:"flow-query"})," covers database access. Don't mix them."]}),"\n",(0,i.jsx)(t.h3,{id:"5-document-the-edge-cases",children:"5. Document the Edge Cases"}),"\n",(0,i.jsx)(t.p,{children:"The 80% cases are obvious. Skills earn their ROI on the 20% that trips up AI:"}),"\n",(0,i.jsx)(t.pre,{children:(0,i.jsx)(t.code,{children:'"When a hook calls bob.runAction(), ALWAYS check the .ok property of the \nresult before continuing. AI tends to assume sub-requests always succeed."\n'})}),"\n",(0,i.jsx)(t.h2,{id:"the-skill-ecosystem",children:"The Skill Ecosystem"}),"\n",(0,i.jsx)(t.p,{children:"Logic Bee maintains a curated set of skills:"}),"\n",(0,i.jsxs)(t.table,{children:[(0,i.jsx)(t.thead,{children:(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.th,{children:"Skill"}),(0,i.jsx)(t.th,{children:"Contract"})]})}),(0,i.jsxs)(t.tbody,{children:[(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"creating-hooks"})}),(0,i.jsx)(t.td,{children:"File structure, decorator metadata, scaffolding CLI"})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"bob-request-api"})}),(0,i.jsx)(t.td,{children:"BobRequest accessors and lifecycle"})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"flow-query"})}),(0,i.jsx)(t.td,{children:"Database operations and tenant scoping"})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"hook-code-style"})}),(0,i.jsx)(t.td,{children:"Naming, formatting, structural rules"})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"hook-validation-rules"})}
1),(0,i.jsx)(t.td,{children:"Hard rules and soft conventions"})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"event-routing"})}),(0,i.jsx)(t.td,{children:"How events dispatch to hooks"})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"connectors"})}),(0,i.jsx)(t.td,{children:"External API integration patterns"})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"interfaces"})}),(0,i.jsx)(t.td,{children:"Type definitions and data factories"})]})]})]}),"\n",(0,i.jsx)(t.p,{children:'Each skill is a contract: "If you follow these rules, the generated code will be correct."'}),"\n",(0,i.jsx)(t.h2,{id:"measuring-roi",children:"Measuring ROI"}),"\n",(0,i.jsx)(t.p,{children:"Before and after skill files:"}),"\n",(0,i.jsxs)(t.table,{children:[(0,i.jsx)(t.thead,{children:(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.th,{children:"Metric"}),(0,i.jsx)(t.th,{children:"Before Skills"}),(0,i.jsx)(t.th,{children:"After Skills"})]})}),(0,i.jsxs)(t.tbody,{children:[(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:"AI-generated hooks needing revision"}),(0,i.jsx)(t.td,{children:"70%"}),(0,i.jsx)(t.td,{children:"15%"})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:"Convention violations per hook"}),(0,i.jsx)(t.td,{children:"3.2 avg"}),(0,i.jsx)(t.td,{children:"0.4 avg"})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:"Time from prompt to merge-ready"}),(0,i.jsx)(t.td,{children:"25 min"}),(0,i.jsx)(t.td,{children:"8 min"})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:"Developer context in prompts"}),(0,i.jsx)(t.td,{children:"5\u201310 lines"}),(0,i.jsx)(t.td,{children:"1 line (skill reference)"})]})]})]}),"\n",(0,i.jsx)(t.h2,{id:"writing-your-first-skill",children:"Writing Your First Skill"}),"\n",(0,i.jsx)(t.p,{children:"Start here:"}),"\n",(0,i.jsxs)(t.ol,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Pick your biggest pain point"})," \u2014 what does the AI consistently get wrong?"]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Write the rule"})," \u2014 prescriptive, with examples"]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Save it"})," to ",(0,i.jsx)(t.code,{children:".agents/skills/your-skill-name/SKILL.md"})]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Test it"})," \u2014 prompt the AI to use the skill and check the output"]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Iterate"})," \u2014 add rules as you find new patterns the AI misses"]}),"\n"]}),"\n",(0,i.jsx)(t.h2,{id:"the-takeaway",children:"The Takeaway"}),"\n",(0,i.jsx)(t.p,{children:"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 \u2014 it's to define the rules that make correction unnecessary."}),"\n",(0,i.jsx)(t.p,{children:(0,i.jsx)(t.strong,{children:"Write the contract once. Get correct code forever."})})]})}function h(e={}){let{wrapper:t}={...(0,r.R)(),...e.components};return t?(0,i.jsx)(t,{...e,children:(0,i.jsx)(c,{...e})}):c(e)}},9844(e,t,s){s.d(t,{R:()=>l,x:()=>o});var n=s(1763);let i={},r=n.createContext(i);function l(e){let t=n.useContext(r);return n.useMemo(function(){return"function"==typeof e?e(t):{...t,...e}},[t,e])}function o(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:l(e.components),n.createElement(r.Provider,{value:t},e.children)}},8764(e){e.exports=JSON.parse('{"permalink":"/blog/skills-as-a-contract","source":"@site/blog/2026-03-02-skills-as-a-contract.md","title":"Skills as a Contract Between AI and Developer","description":"Skills aren\'t documentation. They\'re executable contracts \u2014 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.","date":"2026-03-02T00:00:00.000Z","tags":[{"inline":false,"label":"AI","permalink":"/blog/tags/ai","description":"AI-assisted development and code generation"},{"inline":false,"label":"Architecture","permalink":"/blog/tags/architecture","description":"System architecture and design decisions"},{"inline":false,"label":"Developer Experience","permalink":"/blog/tags/developer-experience","description":"Improving the developer workflow with better tooling and patterns"}],"readingTime":3.31,"hasTruncateMarker":false,"authors":[{"name":"Gabriel Paunescu","title":"Founder CTO Neologic","url":"https://www.linkedin.com/in/gabrielpaunescu/","page":{"permalink":"/blog/authors/gabriel"},"socials":{"x":"https://x.com/gabrielnocode","linkedin":"https://www.linkedin.com/in/gabrielpaunescu/","github":"https://github.com/gp187","newsletter":"https://gabinthelab.com"},"imageURL":"https://substackcdn.com/image/fetch/$s_!3iBT!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F7c26f4db-d3cd-4aff-9abc-b3daff9b6b3f_822x822.jpeg","key":"gabriel"}
1],"frontMatter":{"slug":"skills-as-a-contract","title":"Skills as a Contract Between AI and Developer","authors":["gabriel"],"tags":["ai","architecture","developer-experience"]},"unlisted":false,"prevItem":{"title":"AI-Assisted Data Import Pipelines: A Real-World Case Study","permalink":"/blog/ai-assisted-data-import-pipelines"},"nextItem":{"title":"Debugging AI-Generated Code in an Event-Driven System","permalink":"/blog/debugging-ai-generated-code"}}')}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.