Agent Engineering
Dissecting a Real-World Skill
Using the Alice Release Assistant as an example: click each section to expand details and see how an Agent reads and executes a Skill.
SKILL.md Section-by-Section Breakdown
SKILL.md
alice-release
Alice Project Release Assistant
1
Metadata
Skill name, functional description, trigger phrases
▶
📌 Design decision: The coverage of trigger phrases determines the Skill's recall rate. Too few → the Skill fails to fire when it should; too broad → it fires when it shouldn't. Good trigger phrases = exhaustively listing all natural ways the user might express the request.
2
Applicability Conditions
The decision chain the Agent uses to determine whether to trigger this Skill
▶
User said a trigger phrase?
→
YES
→
Currently in Alice project directory?
→
YES
→
Trigger Skill
↓
NO
→
Use general-purpose capabilities
Similarly, if the second decision node is NO (not in the Alice directory), it also routes to "Use general-purpose capabilities."
When conditions are not met, the Skill exits silently without disrupting normal conversation.
When conditions are not met, the Skill exits silently without disrupting normal conversation.
📌 Design decision: Applicability conditions = a safeguard against accidental triggering. Without them, saying "release" in any project would fire Alice's release workflow — a catastrophic bug.
3
Execution Steps
7-step pipeline: from Git check to landing page sync
▶
Check Git
→
Run Tests
→
Build App
→
Update Version
→
Write Release Notes
→
Upload to COS
→
Sync Landing Page
Click to simulate the Agent executing step by step
📌 Design decision: Step order matters: "run tests then build" vs "build then test"? The step order in a Skill = the SOP you believe is correct. The Agent will follow it strictly.
4
Allowed Tools
The toolkit the Agent can use while executing this Skill
▶
Allowed
run_command
edit_file
read_file
git
web_search
Prohibited
delete_file
agent (cannot launch sub-Agents)
📌 Design decision: Allowed tools = safety boundary. Restricts the weapons the Agent can use while executing this Skill. Prohibiting delete_file prevents accidental file deletion during a release; prohibiting sub-Agents keeps the execution chain predictable.
5
Safety Constraints
Non-negotiable red lines — the Agent's traffic rules
▶
No force push: prevents overwriting others' commits
No skipping tests: no matter how urgent, failing tests mean no release
On failure: stop and report, never auto-retry — return control to humans
📌 Design decision: Safety constraints are the most important part of a Skill. Wrong steps mean the Agent does the wrong thing; missing constraints mean the Agent might do something dangerous. Good constraints = explicit prohibitions + graceful degradation on failure.
More Skill Examples
content-creator
Content creation starting point: complete writing workflow from style analysis to final delivery
Style Profile→
Confirm Requirements→
Outline Design→
Deep Research→
Write Article
Trigger phrases: Help me write, I want to write, draft an article, write a post
Key design: Analyze the user's writing style before drafting — the model doesn't get to generate directly. This ensures every output matches the user's personal style, avoiding generic AI-sounding text.
Tool permissions: Allows web_search (deep research needs internet); prohibits direct publishing (requires human review).
Key design: Analyze the user's writing style before drafting — the model doesn't get to generate directly. This ensures every output matches the user's personal style, avoiding generic AI-sounding text.
Tool permissions: Allows web_search (deep research needs internet); prohibits direct publishing (requires human review).
web-importer
Web importer: save web page content in high quality to WPS Notes
URL Detection→
Content Fetch→
Format Convert→
Write to Note
Trigger phrases: Save this page to notes, import this article, web page to notes
Key design: Automatically detects three page types (WeChat article, Twitter/X, generic web page) and applies different scraping logic. From the user's perspective it's just one request; under the hood there are three strategies.
Safety constraint: Does not save pages that require login (prevents privacy leakage).
Key design: Automatically detects three page types (WeChat article, Twitter/X, generic web page) and applies different scraping logic. From the user's perspective it's just one request; under the hood there are three strategies.
Safety constraint: Does not save pages that require login (prevents privacy leakage).
tag-organize
Tag organizer: scan all tags, find duplicates and chaos, intelligently merge
Scan Tags→
Analyze Duplicates→
Merge Suggestions→
Execute Cleanup
Trigger phrases: Organize note tags, clean up tags, too many tags, tags are a mess
Key design: Present suggestions first, wait for user confirmation, then execute — never auto-merge. This embodies the "human-in-the-loop" design principle.
Safety constraint: Never deletes any tag, only merges; must obtain user confirmation before executing.
Key design: Present suggestions first, wait for user confirmation, then execute — never auto-merge. This embodies the "human-in-the-loop" design principle.
Safety constraint: Never deletes any tag, only merges; must obtain user confirmation before executing.
📌 Core insight: A good Skill = a good SOP. The person writing the Skill is the domain expert; the person using the Skill is the Agent. The ideal Skill granularity is one complete workflow: too coarse and it provides no guidance; too fine and it's not worth encapsulating.
Takeaway
Takeaway — A Skill is an SOP written for an Agent: when to trigger, what steps to execute, which tools are allowed, and what safety constraints apply. Writing a Skill is fundamentally about encoding human expert knowledge into a process an Agent can execute.