Skip to content

Commit 2bdad02

Browse files
dfberrydiberryCopilot
authored
Dfberry patch 6 (#89)
* Create 2026-09-03-create-a-skill.md * Update skill creation blog post Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: diberry <41597107+diberry@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 370e5d2 commit 2bdad02

1 file changed

Lines changed: 133 additions & 0 deletions

File tree

‎website/blog/2026-09-03-create-a-skill.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
---
2+
slug: /2026-09-03-create-a-skill
3+
date: 2026-09-03
4+
canonical_url: https://dfberry.github.io/blog/2026-09-03-create-a-skill
5+
custom_edit_url: null
6+
sidebar_label: "2026.09.03 Create an agent skill"
7+
title: "How to Create Agent Plugin Skills That Work"
8+
description: "Learn how plugins organize agent skills, then compare six public skill creators for routing, structure, testing, and reliable execution."
9+
tags:
10+
- ai
11+
- agent plugins
12+
- agent skills
13+
- GitHub Copilot
14+
- Claude
15+
- Codex
16+
keywords:
17+
- create an agent plugin
18+
- agent plugin skills
19+
- create an agent skill
20+
- SKILL.md
21+
- agent skill creator
22+
- skill routing metadata
23+
- test agent skills
24+
---
25+
26+
# How to create agent plugin skills that work
27+
28+
I wanted a better way to create skills for an agent plugin, so I read six public skill creators to see what they agreed on. A plugin is the top-level package. It can contain several skills, with each skill providing one reusable capability. A portable skill can also stand alone.
29+
30+
## My quick recommendation
31+
32+
- For one portable skill, start with [.NET create-skill](https://github.com/dotnet/skills/blob/main/.agents/skills/create-skill/SKILL.md), then use the [Anthropic skill-creator](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md) evaluation loop.
33+
- For a Codex skill, use the [OpenAI skill-creator](https://github.com/openai/skills/blob/main/skills/.system/skill-creator/SKILL.md) as the design guide.
34+
- For deep operational knowledge, borrow the vocabulary and anti-pattern techniques from the [Forge skill-creator](https://github.com/jdforsythe/forge/blob/master/skills/skill-creator/SKILL.md).
35+
- For a plugin containing a family of skills or a publication pipeline, look at [Skill Forge by AgriciDaniel](https://github.com/AgriciDaniel/skill-forge/blob/main/skill-forge/SKILL.md) or [SkillForge by tripleyak](https://github.com/tripleyak/SkillForge/blob/main/SKILL.md).
36+
37+
## What makes a useful SKILL.md
38+
39+
### The description does the routing
40+
41+
The agent often sees the skill name and description before it loads the full file. Write the description in the words a person would use when asking for help. Include the artifacts, symptoms, or tasks that should trigger the skill.
42+
43+
Also say when the skill should not run. If two skills both claim "GitHub help," the router has little reason to choose the right one. "Review a pull request" and "repair a failing GitHub Actions workflow" are easier to route.
44+
45+
A narrow description can carry both the positive and negative routing signals:
46+
47+
```markdown
48+
---
49+
name: workflow-repair
50+
description: Diagnoses and repairs failing CI workflows. Use for failed jobs, logs, or workflow YAML. Do not use for pull request reviews or feature development.
51+
---
52+
```
53+
54+
### The main file stays lean
55+
56+
Put the instructions needed for most runs in `SKILL.md`. Move long examples, schemas, and domain references into files the agent can open when needed. Put repeatable or fragile operations in scripts.
57+
58+
A lean main file protects the shared context. Every line of background material competes with the task, conversation, and source files the agent also needs.
59+
60+
The main file can name the common path and disclose details only when needed:
61+
62+
```markdown
63+
---
64+
name: release-notes
65+
description: Drafts release notes from completed changes.
66+
---
67+
68+
## Workflow
69+
70+
1. Identify user-visible changes.
71+
2. Draft the summary.
72+
3. Check [the style guide](references/style.md) when wording is unclear.
73+
4. Run `scripts/check-notes.py` before returning the result.
74+
```
75+
76+
### The instructions match the risk
77+
78+
Some work needs judgment. Give the agent principles and room to choose. Other work must happen the same way every time. Give that work a script or a strict sequence.
79+
80+
The OpenAI creator frames this as choosing the right degree of freedom. I find that more useful than treating every skill as a prose prompt. If a missed step can damage data or publish the wrong thing, do not rely on the agent remembering a suggestion buried in a paragraph.
81+
82+
### The skill defines a finish line
83+
84+
Say what the output should contain, how to represent partial success, and when to stop. Include the smallest question the agent should ask when it cannot continue safely.
85+
86+
Without a finish line, a skill can produce a plausible answer while skipping the check that mattered. "Update the file" is weaker than "update the file, run the existing validator, and report any failed checks without hiding them."
87+
88+
The finish line should make output, validation, and stopping conditions explicit:
89+
90+
```markdown
91+
## Finish
92+
93+
- Return the updated file and a short change summary.
94+
- Run `scripts/validate.py`.
95+
- Report every failed check; do not claim completion if validation fails.
96+
- If the target file is unknown, ask for its path and stop.
97+
```
98+
99+
### Activation and execution get separate tests
100+
101+
A skill can work perfectly when you force the agent to use it and still fail in normal conversation because the description never attracts the right prompts.
102+
103+
Test both:
104+
105+
1. Does the skill activate for several realistic requests?
106+
2. Does it stay out of nearby requests owned by another skill?
107+
3. Once selected, does it complete the task and produce the expected result?
108+
109+
Anthropic's creator is especially useful here because it treats skill authoring as a loop: draft, test, review the results, revise, and add the failures to the test set.
110+
111+
## Microsoft and Azure skill examples
112+
113+
These Microsoft-owned repositories provide strong Agent Skill examples for Azure and developer workflows. They are not ranked by usage. Each one demonstrates a pattern worth borrowing:
114+
115+
- The [Azure AI skill](https://github.com/microsoft/azure-skills/blob/main/skills/azure-ai/SKILL.md) routes requests across several AI services while keeping service-specific details in supporting references.
116+
- The [Azure Cost Management skill](https://github.com/microsoft/azure-skills/blob/main/skills/azure-cost/SKILL.md) defines positive and negative routing, required roles, separate workflows, and safety guidance.
117+
- The [Azure SDK pipeline troubleshooting skill](https://github.com/Azure/azure-sdk-tools/blob/main/plugins/azure-sdk-tools/skills/pipeline-troubleshooting/SKILL.md) follows a focused identify, analyze, reproduce, fix, and verify sequence with fallback behavior.
118+
- The [Azure Policy external evaluation authoring skill](https://github.com/Azure/azure-policy/blob/master/ExternalEvaluationPolicies/agent-skills/azure-arg-external-evaluation-policy-author/SKILL.md) shows how permissions, rejection criteria, validation, and stop conditions belong in safety-sensitive work.
119+
- The [ASP.NET Core Web API skill](https://github.com/dotnet/skills/blob/main/plugins/dotnet-aspnetcore/skills/dotnet-webapi/SKILL.md) combines precise exclusions and deep domain guidance with security checks, examples, and a verification checklist.
120+
121+
## A simple way to start
122+
123+
I would create the next skill in this order:
124+
125+
1. Write three prompts that should activate it and three that should not.
126+
2. Draft the description from the words used in those prompts.
127+
3. Write only the instructions needed to complete the common path.
128+
4. Move reusable facts into references and deterministic work into scripts.
129+
5. Test routing and results separately, then revise from the failures.
130+
131+
The [Agent Skills specification](https://agentskills.io/specification) provides the portable base. Platform guidance, such as the [GitHub Copilot agent skills overview](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills), adds its own locations and runtime behavior. When skills are packaged in a plugin, keep plugin discovery and runtime rules separate from the portable skill instructions.
132+
133+
I came away with a practical test: can the agent find this skill from a normal request, and can it finish the work without guessing? If both answers are yes, `SKILL.md` is doing its job.

0 commit comments

Comments
 (0)