Agentic Skills
Motivation
Much of my daily work consists of tasks I perform repeatedly: generating a banner, scaffolding a recipe page, formatting a data table to a fixed specification. Each repetition re-issues essentially the same instructions to an agent, which is wasteful. A skill eliminates that waste by encapsulating the workflow once and invoking it by name thereafter. Two questions justify the practice: why encapsulate a workflow as a skill at all, and why author my own rather than rely on existing ones.
Why a Skill
The banner for this post illustrates the mechanism. A single short request invoked my /ph-image skill, and the agent carried out the rest of the workflow:
- Located the skill in my skill repository.
- Loaded its instructions into context.
- Executed a Python script that calls the Gemini API to render the image.
The value extends beyond fewer keystrokes. Composing an effective image prompt is itself a discipline: the model needs a precise, richly specified description to return a usable result, and that description must stay consistent for a set of banners to share one visual identity. Working from the skill’s accumulated conventions, the agent writes such a description more reliably than I would by hand. I supply the subject; the skill governs how it is requested. That division of labor is the point: intent remains with me, execution moves to the skill.
Why My Own
Installable skills are abundant, and two that I rely on mark the opposite ends of the design spectrum:
- Everything Claude Code (ECC): an expansive, all-inclusive plugin whose own README advises selective installation.
- Waza: a deliberately minimal set of eight skills covering the common cases of general development, both coding and otherwise.
Both are excellent, and the catalog of community skills grows continuously. Neither, however, can anticipate the workflows particular to one person’s practice. Authoring a skill is inexpensive, and that low cost is precisely what makes it worthwhile to cover the cases the market never will. The rest of this post documents how I build skills around my own needs, and how you might do the same.
A Minimum Construction
At minimum, a skill is a directory bearing the skill’s name and containing a single SKILL.md file:
Minimal in form does not imply minimal in function. My /ph-html skill has exactly this structure, one directory and one Markdown file, yet it produces every styled HTML component across my blog posts and slides, including those in this post. A single file, invoked everywhere, yielding a consistent result.
SKILL.md comprises two parts: a YAML frontmatter block and a body. The frontmatter declares the skill’s name and a description, the latter being the text the agent reads to decide whether to trigger the skill. The body is the prompt loaded into context on invocation, stating the rules, conventions, and examples the agent is to follow. The structure, abridged from /ph-html:
---
name: ph-html
description: Generating styled HTML components for Quarto blog posts.
Five component types: intro-links, button-table, table, icon-grid, url.
---
# Skill: ph-html
Use this skill when generating styled HTML components for Quarto blog posts.
## Common Conventions
- All styles live in `styles/styles.scss`. Never add `<style>` blocks.
- Use 1-space indentation per level in HTML.
## intro-links
A centered row of pill buttons near the top of a post.
```html
<div class="intro-links">
<a href="..." class="intro-btn">Website</a>
</div>
```This is the complete anatomy: a name, a description, and a body specific enough that the agent reproduces the intended output on each invocation. Everything that follows is elaboration on this foundation.
A More Complex Example
As one grows more fluent with skills, it becomes clear that a skill is more than a body of instructions and constraints. It can also carry templates and deterministic resources, and the reason is rooted in how language models behave. An LLM is inherently stochastic: given only an instruction file such as SKILL.md, the agent reconstructs the output afresh on each run, admitting variation that is often unwelcome. Solidified resource files supply the opposite property. A code script, a stylesheet, a template, or a shell command is a fixed artifact, identical on every invocation, and folding such files into a skill pins down the parts of a workflow that must not vary.
My /ph-slide skill is built on this principle. Alongside the main SKILL.md, it ships two folders of resources:
assets/holds the deterministic building blocks: a shared stylesheet, the deck configuration, and a render script.template/is a complete Quarto slide project that serves as a working template to copy and adapt.
A Quarto deck draws on several file types at once (.qmd source, .scss styling, .yml configuration, .html partials), so reproducing that scaffolding from instructions alone would be both tedious and unreliable. A semi-deterministic template, fixed resources the agent copies and adapts rather than regenerates, is the most efficient route to consistent slide decks.