TL;DR: 一個 skill 會多可預測,大概就看它的邊界劃得多清楚。把它當成「能力」(這個 skill 讓 AI 會做 X),它容易亂跑;把它當成「合約」(講好輸入、輸出、以及它不會碰什麼),它就比較像一個設計良好的 API。重點不是寫更多「要小心」,而是把它能碰的範圍框住。

我有個 skill,前一天還用得好好的,隔天就開始亂搞:我要它做 A,它順手把旁邊的 B 也「幫我」改了。我第一個反應是怪模型今天狀況不好。後來才想通,問題在我自己——當初寫這個 skill 的時候,我只說了它「會做什麼」,沒說它「不能碰什麼」。

這是英文版的中文對照,英文那篇用 API 設計的角度談;這篇是我自己怎麼從「能力」這個想法,慢慢搬到「合約」這個想法的過程。

能力清單 vs 合約

我們很習慣用「能力」來描述一個 skill:「這個 skill 讓 AI 會跑測試」「這個會幫我部署」。這種講法很自然,也很容易讓你之後被嚇到。因為「會跑測試」這句話沒有邊。它沒講會讀什麼、會動什麼、遇到不在預期內的狀況時會怎麼處理。

合約天生就有邊。它講清楚什麼東西進去、什麼東西出來、以及哪些地方它不會碰。框架文件裡有一句講得比我直接:skill 應該被當成「有版本、受政策約束、能力被框住的封裝」,而不是「一堆鬆散的 prompt 檔」。這跟一個 AI Skill 和 Prompt 到底差在哪講的是同一件事:重點不是 AI「能」做那件事,而是那件事被「講清楚」了。

合約先行:先想清楚它不該做什麼

我看過一個還算貼切的比喻:skill 像是你交給一位很強的廚師的食譜。食譜提供的是結構:材料、順序、限制;廚師提供的是判斷,什麼時候醬汁該再收一下、什麼時候可以換個材料。你不會因為廚師很強,就把食譜寫成「做一道好吃的菜」。

skill 也一樣。模型本身的判斷力很好,所以你要補的不是判斷,是結構。而結構裡最常被漏掉的,就是那條「不要碰」的線。我現在寫一個 skill,會先問自己一個問題:這個 skill 最不該做的事是什麼? 把那條線寫進去,比再多寫三條「請謹慎處理」都有效。

邊界鬆掉,其實是一次沒講的破壞性變更

框架裡有一個原則我覺得很受用:寧可在邊界上把關,也不要去微管模型怎麼想。一個會亂跑的 skill,你通常修不好它的「想法」;你能做的是把它能碰的範圍(哪些檔案、哪些工具、多少預算)框起來。

一個 skill 的範圍如果隨著時間悄悄變大,那其實是你發佈了一次「破壞性變更」卻沒有改版本號。而呼叫它的人(就是你自己)會用最經典的方式發現這件事:在出事的時候。這也是AI 代理常見痛點裡那個「能力邊界」缺口最貴的一種表現形式。範圍,只是它最容易爆出來的地方。

我把一個 skill 從能力改成合約的前後

回到開頭那個亂改 B 的 skill。它原本的描述大概是「整理這個模組的程式碼」。很開放,聽起來很厲害,結果就是它對「整理」的理解跟我不一樣。

我後來把它改寫成比較像合約的樣子:輸入是「指定的那幾個檔案」,輸出是「格式化後的同一批檔案 + 一份它改了什麼的清單」,然後明確寫上「不要新增或刪除檔案、不要碰指定範圍以外的東西」。改完之後它沒有變笨,只是不再自作主張。差別不在能力,在邊界。

順帶一提,邊界清楚的 skill 通常也比較便宜。skill 是漸進載入的:AI 先讀那一小段 metadata 判斷現在用不用得上,真的要用才載入完整內容。一個邊界小而清楚的 skill,光看它的「合約」就能被快速略過;一個什麼都做的 skill,得把整包拖進 context 才發現其實不該用它。這跟我在 Token 成本那篇講的是同一個方向:清楚的小合約,既好預測也比較省。

還在摸索

老實說,一個 skill 該有的合約長什麼樣,我很少一開始就想對。通常是看它在哪裡越界,再把線畫在那裡。但這個框架本身,先講好它承諾什麼、它不碰什麼,然後把對這兩者的任何更動都當成一次正式的改版,到目前為止站得住。

Agentic OS 是開源專案:github.com/KbWen/agentic-os

延伸閱讀

• 只會 Prompt 已經不夠了:從「下指令」到「蓋系統」 — Skill 是這個系統思維裡的其中一層,先弄清楚整張地圖
• 只用 Prompt 和技能,也能做到基本治理 — 把合約思維用在 Skill 之外的層面:記憶檔、範圍宣告
• Work Log:跨 session 的記憶機制 — Skill 解決能力邊界,Work Log 解決時間邊界

TL;DR: An agent skill behaves predictably to about the degree its boundary is specified. Described as a capability (“the agent can now do X”), a skill tends to drift. Described as a contract (declared inputs, declared outputs, a scope it promises not to exceed), it behaves more like a well-designed API. The interface-design habits engineers already have (stable contracts, explicit scope, versioning) seem to transfer directly. The framework’s own direction points the same way: skills as versioned, capability-bounded packages, with boundary enforcement instead of micromanaging how the model reasons.

Every team that has shipped a public API has lived through the same lesson: an endpoint that does “roughly what you’d expect” is a liability. The contract (what it accepts, what it returns, what it won’t touch) is the product. The implementation behind it is replaceable. Agent skills seem to be arriving at the same lesson, just faster.

A skill, in Anthropic’s Agent Skills standard (now shared across Claude Code, Codex, and Cursor), is a SKILL.md file: instructions plus frontmatter that controls when it loads and who invokes it. That format makes it tempting to think of a skill as “a prompt the agent can reuse.” That framing is where a lot of the unpredictability starts.

A skill is a contract, not a capability list

The usual way to describe a skill is by capability: “this one runs the test suite,” “this one deploys.” It reads naturally and it sets you up to be surprised. A capability has no edges. “Can deploy” says nothing about what it will read, what it will change, or what it will do when the situation doesn’t match the happy path.

A contract has edges by construction. It names what goes in, what comes out, and what stays out of reach. The framework’s own architecture notes put it more bluntly than I would: skills should be treated as “versioned, policy-governed, capability-bounded packages,” not “loose prompt files.” The same idea runs through what makes a skill different from a prompt: the value is in the specification, not the raw capability.

The principles that transfer

If a skill is an interface, then the design vocabulary engineers already use mostly carries over:

None of this is novel to anyone who has designed an interface. The only move is recognizing that a skill is one, and that “be more careful” is not a substitute for a specified boundary—the same way “use the API responsibly” was never a substitute for a schema.

Scope drift is a breaking change

The most common failure I see isn’t a skill that can’t do its job. It’s a skill that does its job plus two things nobody asked for, because its scope was never drawn.

The framework’s design principle for this is worth borrowing: boundary enforcement over behavior micromanagement. You don’t fix a vague skill by adding more instructions about how to reason well. You constrain what it can reach—which files, which tools, which budget. A skill whose scope widens over time is shipping a breaking change with no version bump, and the caller (you) finds out the way callers always find out: in production. This is the same capability-boundary gap behind several of the common agent pitfalls; scope is just the place it shows up most expensively.

The boundary has a token price too

There’s a second reason to draw the edge tightly, and it connects to cost. Skills load progressively: the agent reads a skill’s small metadata to decide whether it’s relevant, and only pulls the full body when it is. A tightly-bounded skill is cheaper to ignore: its contract is small and quick to probe, where a sprawling one drags its whole body into context to find out it didn’t apply. Interface discipline and token discipline end up pointing in the same direction: a clear, small contract is both more predictable and less expensive.

A skill with a fuzzy boundary isn’t really a capability. It’s an undocumented API, and it will surprise you for the same reasons undocumented APIs always have. I don’t think the right contract for a given skill is obvious up front—I usually find it by watching where a skill oversteps and drawing the line there. But the framing has held up: define what it promises, define what it won’t touch, and treat a change to either as the breaking change it is.

This post is part of a series on building real AI systems. Related: What Makes an AI Skill Different from a Prompt? and Beyond Prompts: From Giving Instructions to Building Systems. A Chinese companion piece on skill boundaries is Skill 邊界設計:從能力到合約. The framework is open source at github.com/KbWen/agentic-os.

TL;DR： 在裝任何框架之前，有一層治理是免費的：在專案根目錄放一個 AGENTS.md 或 CLAUDE.md，養成開口要求 evidence 的習慣，開始任務前先說清楚什麼不能動。這三件事不能替代跨 session 的狀態管理，但能擋掉大部分常見問題。這篇說的就是怎麼做、做到什麼程度、在哪裡會失效。

有一段時間我的 Claude Code 工作流裡沒有任何框架，只有對話和一堆臨時 prompt。某天我做了兩個改變：把專案的架構決策寫進一個 CLAUDE.md，還有在每次 AI 說「好了」的時候問一句「commit SHA 是什麼？」

一類問題幾乎消失了：AI 在新 session 裡對著不存在的設計模式寫程式碼的情況，以及我接受了「完成」卻發現什麼都沒變的情況。不是所有問題都解決了。但那兩件事的性價比，讓我後來開始認真想「在裝框架之前，這個層面的治理到底能做多少」。

這篇是AI 代理常見痛點與我們的嘗試的延伸。那篇列了五個反覆出現的問題，這篇專門回答：只靠 prompt 習慣和 skill 選擇，能解決多少？

記憶檔案：解決跨 session 失憶的最低成本方案

AI 代理在每一個新對話都是空白狀態。它不記得上次的架構決策，不記得你說過不要用哪個 pattern，也不記得你已經有一個 utils/auth.ts，所以它再寫一個新的。這個問題在 IEEE Spectrum 的報導裡有量測數據：長 session 後期，AI 重複生成已存在函式、忽視早期建立的 coding convention 的頻率明顯上升。

三個工具在試圖解決同一個問題：

AGENTS.md 是 OpenAI Codex 最初設計的慣例，後來被 Cursor、GitHub Copilot 和 Google Antigravity 等主流工具廣泛採納。它的設計邏輯是：在任何工具讀取它之前，先告訴工具「這個專案是怎麼運作的、你可以做什麼、不可以做什麼」。

CLAUDE.md 是 Anthropic 針對 Claude Code 的版本。Claude Code 在每個新 session 開始時自動注入這個檔案的內容，所以你放在這裡的東西就等於是每次都在對話開頭重新說一遍。

.cursor/rules 是 Cursor 的對應物。原理相同。

這三個慣例同時存在，說明「怎麼讓 AI 記住專案規則」這個問題是通用的，不是某個工具特有的。選哪個取決於你主要用什麼工具，你不需要三個都放，放一個就有效果。

這類記憶檔案最有用的內容通常是三類：架構限制（「這個 repo 用 Repository pattern，不要把業務邏輯寫進 controller」）、命名規範（「service 命名用 XxxService，不要用 XxxManager」）、以及「不要碰」清單（「/database/migrations 只有在明確被要求的時候才能動」）。

一個重要的注意：這類檔案要短。研究觀察和實踐都指向同一個上限：200 行、2000 token 以內。超過這個長度，重要的規則會被稀釋。AI 技術上還是讀了整個檔案，但前面讀到的東西到後面已經注意力不足。寫 CLAUDE.md 的時候，如果你覺得需要加第六條規則，先問自己第一條能不能刪掉。

Skill 選擇：要求愈具體，干擾愈少

在 Claude Code 或 Cursor 的一次工作 session 裡，你可以載入很多 context：整個 codebase 的 README、過去的對話歷史、多個技能文件。但「載入愈多愈好」是個陷阱。

一個改一行 typo 的任務，不需要知道整套測試策略、部署規範和 API 設計原則。把這些全部塞進 context，不會讓 AI 更謹慎，只會讓它在「哪些規則現在適用」這件事上分配更少的注意力給真正重要的那個。

這不是 Agentic OS 特有的問題，是任何 Claude Code 或 Cursor session 都存在的情況。具體做法是：開始一個任務之前，先想清楚這個任務需要知道什麼，然後只提供那些。一個 tiny-fix 說「這是那行 code，幫我修」就夠了；一個涉及多個模組的功能開發才需要交代設計模式、測試策略和資料庫規範。

結果是給了 AI 密度更高的相關資訊，不是更少的資訊。

Evidence 習慣：不問則不說

這是成本最低的一個改變，也是讓我最驚訝的一個。

AI 說「完成了」的時候，它有可能真的完成了，也有可能完成了 90% 然後遇到小問題就繞過去了，也有可能整個理解方向就錯了。這三種情況在它的輸出裡，有時候看起來幾乎一樣。

養成一個習慣：在接受任何「完成」之前，要求一個具體的 artifact。

不是一個表單，也不是一套流程，就一句話：「commit SHA 是什麼？」「把 test 跑一遍，貼輸出給我」「你改了哪個檔案，第幾行？」

這個習慣有效的原因不只是讓你可以查。問這個問題本身會讓 AI 把它沒說清楚的地方說出來。 很多時候，我問「測試有過嗎」，它才會說「啊，那個測試我還沒跑，因為 X 的 setup 有問題」，而這個資訊如果我沒問，它可能就默默略過了。

誠實地說：這個習慣很累。問了十幾次之後你開始理解為什麼人們想要自動化這件事，框架裡的 evidence gate 就是把這個問答自動執行。但作為一個習慣，它能擋掉大概六七成的「接受了看起來完成的東西、後來發現沒有」的情況。

範圍宣告：先說不要碰什麼

開始一個複雜任務之前，明確告訴 AI 它應該不要碰什麼。

具體的說法比模糊的說法有效：「你在做 authentication module。除非我明確說，不要碰 /api/payments 和 /database/migrations 底下的任何東西」比「專注在 auth 就好」有用得多。

原因不完全是「AI 會遵守」，它不是每次都遵守。而是宣告了邊界之後，AI 在不確定的時候開始問問題而不是自己決定。我給了這樣的指令之後，在它原本會直接去改 payments module 的地方，它變成問我「這邊需要我更新 payment 的驗證邏輯嗎？」——這個轉變很有價值。

這個觀察跟 Pete Hodgson 對 AI coding assistant 失效模式的分析有直接的關係：當一個問題存在很多可能的解法，AI 選中你心目中那個的機率趨近於零。把解法空間縮小（也包括把「不能碰的部分」明確劃出來），大幅提高了它走向你要的方向的機率。這是流程問題，跟模型能力無關。

在從「下指令」到「蓋系統」裡，我說過「AI 只活在那一次的對話框裡」。宣告範圍是在這個限制之內，盡量讓它知道那個對話框的邊界在哪裡。

這個層面的治理做到什麼、做不到什麼

做得到的：讓 AI 在新 session 裡記得你的架構決策（記憶檔案）。讓它在不確定的時候問你而不是自己做決定（範圍宣告）。讓你在接受輸出之前有一個具體的查核點（evidence 習慣）。把技能文件控制在合理長度，避免注意力被稀釋（skill 選擇）。

做不到的是跨 session 的連貫狀態。記憶檔案解決的是「規則記得住」的問題，不是「上次做到哪裡」的問題。如果你的任務橫跨多個 session，每次開始你還是要手動交代背景——或者接受 AI 從頭重推一遍。Evidence 習慣的疲勞感也是真實的：問個五十次之後，你會想要自動化。這不是壞事——這是你已經知道在哪裡需要更正式的結構的訊號。範圍宣告在複雜任務下同樣會降解，涉及的模組愈多，「先說不要碰什麼」就愈難窮舉。

這個層面的治理是真實的，不是「沒有框架的窮人版」。但它有天花板。當你開始覺得每次的 context 交接很重複、evidence 問答讓你厭倦、範圍宣告的清單比任務本身還長——那就是你已經碰到這個層面的邊界了。

下一篇：Work Log：跨 session 的記憶機制

Agentic OS 是開源專案，記憶檔案的範本和設計說明都在這裡：github.com/KbWen/agentic-os

延伸閱讀

• AI 代理常見痛點與我們的嘗試 — 這篇治理技巧主要在解這五個反覆出現的問題
• MCP 資安危機：問題不在協定，而在治理 — 同一個治理缺口在工具串接層的延伸版本
• Token 成本的真相：分級，但別分太細 — Evidence 跟記憶檔不是免費的，但這些成本是有上限的

TL;DR: A “Skill” in production AI is not a saved prompt — it’s a capability abstraction layer with a defined input schema, tool bindings, validation, and retry logic. This post explains why that distinction matters and how Skills fit between raw model calls and higher-level agent orchestration.

This post is part of a series on building real AI systems. If you haven’t read the previous piece on moving beyond prompts, that’s a good place to start.

Introduction

Most people treat AI skills as glorified prompt templates.

Honestly, that’s fair. A lot of products market “skills” as saved instructions with a nicer UI. You click a button, it loads some text into the system prompt, done.

But in a real production system, a Skill is something different.

It is a capability abstraction layer—sitting between raw model calls and the higher-level orchestration that actually does something useful. If prompts are like making direct API calls, Skills are the first layer of actual software architecture you build on top of them.

That distinction sounds abstract right now. It starts to matter a lot once your system gets complicated.

Prompt Templates Fall Apart Eventually

Prompt templates are fine to start with. Quick to write, easy to understand, and they work.

Until they don’t.

Say you’re building a basic content pipeline:

Research topic
→ Draft outline
→ Write article
→ Review tone
→ Check SEO
→ Generate metadata

Six steps. You write six prompts. Seems manageable.

A few months later, the pain starts showing up in small ways:

• You copy-paste prompt logic into a new workflow and tweak it slightly. Then again. Now you have three versions that are almost identical but not quite.
• Someone changes the output format for one prompt. Two other steps break silently.
• You add a tool integration to one flow. You realize you need the same thing in three other flows and now you’re doing it manually each time.
• Retry logic gets bolted onto individual prompts in different ways depending on who wrote them.

None of these problems are catastrophic on their own. Together, they quietly accumulate until you realize you’re maintaining a pile of interconnected prompt strings that nobody fully understands anymore.

That’s the moment when prompts stop being instructions and start being infrastructure—but without any of the structure that makes infrastructure manageable.

This is where Skills become necessary.

A Skill Is a Capability Contract

Here’s a useful way to think about it:

A Skill is a standardized interface around a model capability.

Not around a prompt. Around a capability.

In practice, a properly designed Skill specifies a lot more than the prompt text itself:

name: blog_writer

inputs:
  - topic
  - audience
  - tone

tools:
  - web_search
  - knowledge_base

constraints:
  - markdown_output
  - seo_friendly
  - no_ai_tone

validation:
  - min_word_count
  - heading_structure_check

retry_policy:
  max_attempts: 2

Once you’re writing something like this, you’re not really doing prompt engineering anymore. You’re doing interface design.

The prompt probably still exists somewhere inside the implementation. But from the outside, what you’ve defined is:

Input schema → Capability execution → Validated output

That’s much closer to an API or a microservice than a prompt. And it behaves like one—you can test it independently, version it, swap the implementation without changing the callers.

Why This Actually Matters for Workflows

The main reason Skills are useful is that workflows need stable interfaces to call into.

Without that abstraction, every workflow ends up owning its own prompting logic:

Workflow step 1:  raw prompt A
Workflow step 2:  raw prompt B
Workflow step 3:  raw prompt C

Which means your orchestration logic and your model interaction logic are completely tangled together. Changing one touches the other. Reusing anything requires copy-pasting.

With properly defined Skills, a workflow looks more like this:

research_skill()
summarize_skill()
outline_skill()
writer_skill()

Now the workflow doesn’t care how writer_skill works internally. It just knows what it takes and what it produces. You can improve the skill, swap the model, change the prompt—the workflow doesn’t need to know.

Some other things this unlocks: you can attach logging and metrics at skill boundaries instead of burying them in prompts. You can run evaluations on individual skills. Multiple workflows can call the same skill without duplicating logic. Teams can work on skills independently without stepping on each other’s orchestration code.

It’s modular design. The same reasons it works in software apply here.

You Can Get the Granularity Wrong

Skills aren’t free. Over-abstracting creates its own problems, and it happens a lot when teams first discover this pattern.

If you cut things too fine:

title_generator_skill
intro_writer_skill
paragraph_writer_skill
conclusion_writer_skill

Now you’ve created a pile of tiny skills that don’t do anything useful on their own and require elaborate orchestration to combine. You’ve traded one mess for a different mess.

Go too broad instead:

content_engine_skill

And you’ve got a black box that’s hard to test, hard to improve, and not actually reusable across contexts.

The rule is the same as software modularity has always been: a Skill should represent one reusable capability boundary. Not one prompt. Not an entire workflow. One coherent capability.

Getting that boundary right takes some iteration. That’s normal.

Where Skills Sit in the Stack

A practical architecture for a production AI system usually looks something like this:

Each layer has a distinct job:

The reason this layering matters is that a common mistake in AI product design is collapsing everything into the model layer—treating model behavior as the architecture itself. That works for demos. It falls apart as soon as you need to maintain, test, or scale anything.

The model is one layer. A useful one, obviously. But still just one layer.

The Shift from Prompting to Engineering

There’s a specific moment in building AI systems where you stop interacting with models and start designing machine capabilities. It’s not always obvious when it happens, but you usually notice it in retrospect.

Skills are often where that shift shows up concretely.

Before Skills, most of your effort goes into getting the model to do the right thing in a given context. After Skills, you’re thinking about interfaces, contracts, validation, reuse—the same concerns that show up in any software system.

The underlying craft changes. It’s still prompt engineering in places, but the bigger picture is system design.

Conclusion

Prompting is still useful. It’s the basic interaction primitive for working with AI models and it’s not going away.

But prompts alone don’t constitute architecture.

When you need your system to be maintainable, testable, and reusable—when multiple workflows need to share behavior, when you need consistent tooling and validation across the system—you need an abstraction layer above raw prompting.

That’s the Skill layer.

The short version:

Prompts help you use AI.
Skills help you build with AI.

Once you’re building with AI, you’re doing system design. The sooner you design the system intentionally, the less you’ll be untangling it later.

Skills are the capability layer. The layer above — orchestrating agents to do real work — is where governance starts to matter. If you’ve hit unpredictable agent behavior, Why AI Agents Go Wrong: It’s Not the Model covers why most of those failures are structural, not capability, problems.

FAQ

Q: What is an AI Skill?
An AI Skill is a reusable capability abstraction that wraps model behavior with defined input/output schemas, tool access, validation, and retry logic. Unlike a prompt, it exposes a stable interface that other system components can depend on.

Q: What’s the difference between a prompt and a skill?
A prompt is a raw instruction sent to a model. A Skill is a structured capability contract—it defines inputs, tooling, constraints, and validation around that interaction, making it reusable, testable, and composable within larger systems.

Q: When should I use Skills instead of prompts?
When you need the same behavior across multiple workflows, when you want to test or evaluate model behavior independently, or when you need consistent tooling and retry logic across your system. If you’re using a prompt in more than one place, it’s probably worth wrapping it into a Skill.

Q: How do Skills relate to Agents and Workflows?
Skills sit between the tool layer and the workflow layer. Workflows orchestrate sequences of Skill calls. Agents add dynamic decision-making on top of that—choosing which Skills to invoke based on context. Skills are the stable building blocks both depend on.

Read next

• Skill Design as Interface Design — A skill behaves predictably to the exact degree its boundary is specified
• Why AI Agents Go Wrong: It’s Not the Model — Most agent failures aren’t model problems, they’re governance problems
• Token Economics of AI Agent Governance — Governance has a bounded, knowable token cost; ungoverned work doesn’t