Agent Skills give an AI agent the instructions, resources and tools needed to perform a specialised task. They can capture an organisation’s templates, rules and working practices, then make that knowledge available through a natural-language request.
Creating a reliable Agent Skill takes more than writing a long prompt.
We learned this while building a Theta Assist skill to produce Word documents using Theta’s corporate template. The request sounded straightforward: whenever someone asked for a Word document, the skill should use Theta’s fonts, artwork, layouts and styles.
The first result contained many of the right technical components. Visually, it barely resembled the template.
Several iterations later, the skill was accurate, faster and easier to maintain. The experience produced five useful lessons for anyone creating custom Agent Skills.
What is an Agent Skill?
Agent Skills is also the name of an open format for extending AI agents with specialised knowledge and workflows. Under the specification, a skill is a folder built around a SKILL.md file containing metadata and instructions. It can also bundle scripts, reference documents, templates and other assets.
This structure supports progressive disclosure: an agent can use lightweight metadata to discover a skill, load its main instructions when the skill activates, and retrieve detailed resources only when required. That makes Agent Skill the most useful term for this article, with skill used as shorthand.
1. Define success from the user’s perspective
Our initial requirement focused on using Theta document styles. The first skill interpreted that literally. The generated file contained Theta style names, fonts and image assets, but the cover structure had disappeared and the background artwork failed to render.
The skill had followed part of the instruction while missing the expected outcome.
We replaced the broad requirement with observable acceptance criteria:
- The first page must display the approved cover artwork.
- Cover and body sections must remain separate.
- Headers, footers and page numbering must stay intact.
- Content must use approved paragraph, heading, list and table styles.
- The final document must pass structural and visual checks.
When creating a skill, describe what a successful user should receive. Technical instructions can then support that outcome. The same principle applies when selecting a wider platform: our guide to choosing an enterprise GenAI platform covers the governance, sharing and operational controls needed to manage assistants and skills at scale.
2. Give the skill the right method
The first version effectively recreated the document body. This copied some Theta resources but lost the relationships responsible for the original layout.
A Word file can contain anchored drawings, content controls, themes, numbering definitions, section settings and relationships between multiple XML files. Rebuilding it introduced too many opportunities for those connections to break.
The skill was changed to begin with a copy of the approved template and edit its existing structure in place. It replaced specific text and inserted new content while preserving the cover, artwork, headers, footers and sections.
Agent Skills need guidance on both the desired result and the safest method for producing it. This becomes especially important when they handle complex files, business systems or governed processes. Our example of using Theta Assist with Webflow MCP shows the same approach applied to a CMS workflow: inspect the target system, understand its schema, then use the connected tool to complete the task.
3. Prepare skill resources for automation
The original Theta template was designed for people. It included nine pages of instructions, examples and demonstration content.
Those examples helped human authors understand the available styles, but they added processing time and made automated editing more fragile. Early scripts relied on the position of elements within the file, which could change whenever the template was updated.
We created a three-page automation-ready template that retained:
- Theta branding and cover artwork
- Approved styles and numbering
- Headers and footers
- Document-control sections
- Tables, captions and statement styles
Stable bookmarks were then added for the title, date, body content and approvals. A manifest recorded these insertion points and the approved style identifiers.
This gave the skill a clear map of the template. It also reduced rendering time and made future changes safer.
This maps closely to the Agent Skills specification, which separates the main SKILL.md instructions from optional scripts, references and assets directories.
4. Convert critical instructions into validation
One iteration included a clear rule to preserve cover artwork, yet the output still lost the background image. The artwork was stored inside an apparently empty paragraph. When the skill removed that paragraph, it also removed the drawing relationship responsible for displaying the image.
The preservation rule was expanded to cover empty-looking paragraphs, content controls, anchored drawings and image relationships. Automated validation then compared the output with the approved template.
The validator checked that:
- Required cover drawings remained.
- Artwork was still actively referenced.
- Image relationships resolved to valid files.
- Cover and body sections remained intact.
- Styles, numbering, themes, headers and footers were preserved.
The document was also rendered for visual review. Structural validation could confirm that an image relationship existed, while visual inspection confirmed that the image actually appeared.
5. Improve performance without weakening controls
A later version generated documents more quickly, but some accuracy safeguards had been simplified. Its validator checked whether any drawing existed anywhere in the document rather than confirming that every required cover drawing remained.
Performance testing showed that document construction was already quick. Rendering accounted for most of the processing time. This led to a more focused workflow:
- Validate the approved template.
- Insert all content in one pass.
- Run fast structural checks.
- Stop if a required component has changed.
- Render the document once.
- Inspect the final pages.
The streamlined template reduced processing time further. The final skill typically built a document in around 0.06 seconds, completed structural validation in around 0.08 seconds and rendered a five-page file in approximately two seconds.
Optimisation should target the measured bottleneck while retaining the controls that protect output quality. For workflows that also require consistent information from users, AI forms in Theta Assist provide another way to structure inputs before an assistant or skill takes action.
Treat Agent Skill creation as product development
Our first version was a reasonable interpretation of a short requirement. Real-world testing revealed the details it lacked.
Each iteration converted a failure into a reusable improvement:
- Missing design became explicit acceptance criteria.
- Recreated documents became controlled template editing.
- Fragile positions became named bookmarks.
- Lost artwork became relationship validation.
- Slow processing became a measured, single-render workflow.
This is a useful model for Agent Skill development. Start with a defined business outcome, test the skill on realistic work and turn each lesson into an instruction, resource, script or automated check.
A mature Agent Skill is more than a prompt. It is a packaged business process that combines AI flexibility with approved resources, reliable methods and clear quality controls.
Theta Assist helps organisations build these reusable skills around their own knowledge and ways of working, making specialised processes easier for teams to access and apply.
Book a demo to explore how Theta Assist can help your organisation turn specialist knowledge and repeatable processes into reliable Agent Skills.
