Skip to main content

How to Create Agent Plugin Skills That Work

· 6 min read

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.

My quick recommendation​

What makes a useful SKILL.md​

The description does the routing​

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.

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.

A narrow description can carry both the positive and negative routing signals:

---
name: workflow-repair
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.
---

The main file stays lean​

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.

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.

The main file can name the common path and disclose details only when needed:

---
name: release-notes
description: Drafts release notes from completed changes.
---

## Workflow

1. Identify user-visible changes.
2. Draft the summary.
3. Check [the style guide](references/style.md) when wording is unclear.
4. Run `scripts/check-notes.py` before returning the result.

The instructions match the risk​

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.

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.

The skill defines a finish line​

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.

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."

The finish line should make output, validation, and stopping conditions explicit:

## Finish

- Return the updated file and a short change summary.
- Run `scripts/validate.py`.
- Report every failed check; do not claim completion if validation fails.
- If the target file is unknown, ask for its path and stop.

Activation and execution get separate tests​

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.

Test both:

  1. Does the skill activate for several realistic requests?
  2. Does it stay out of nearby requests owned by another skill?
  3. Once selected, does it complete the task and produce the expected result?

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.

Microsoft and Azure skill examples​

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:

A simple way to start​

I would create the next skill in this order:

  1. Write three prompts that should activate it and three that should not.
  2. Draft the description from the words used in those prompts.
  3. Write only the instructions needed to complete the common path.
  4. Move reusable facts into references and deterministic work into scripts.
  5. Test routing and results separately, then revise from the failures.

The Agent Skills specification provides the portable base. Platform guidance, such as the GitHub Copilot agent skills overview, 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.

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.

Maintaining AI Slop Over 2 Years

· 5 min read

Two years ago seems like decades in the world of AI. AI slop wasn't a term I was familiar with, and the project I started with AI was meant to be short-lived—a stopgap until systems and people caught up to support the work.

Woman on road littered with debris

Stage 1 - time-savings over process design​

Because it was meant to be a short-term solution, I didn't care about the what or how as much as the output and time savings. I didn't spend much time on it and certainly didn't architect it in any meaningful way. It was a markdown file - a prompt.

Back then, there was little concern for context size and the only harnesses were custom-made or 3rd party like LangChain.

It read source code and output what I asked it to based on my ever-growing prompt file. I fiddled with it when I had time but usually just took the output and made manual edits as needed.

Stage 2 - shifting sands of source code​

There were a few bumps in the road that caused the prompt file to sputter and halt. The related source code repo moved. That was just one place in the prompt file - an easy change. Then the source code repo completely refactored into a monorepo - that was much harder. The prompt file was looking at specific folders, files, classes and property names. A much bigger change to the prompt file. And of course, I still had other things to do.

Then the source project became much more popular and the feature set grew. Lots of changes and additions. This resulted in a short cycle of my wondering if AI, or my prompt file needed another rewrite.

At this point, I thought regex and a script might be faster. Leave any LLM decision/transition until later.

This was becoming an experiment in how to gain efficiency in a rapidly changing AI world.

Stage 3 - back to reality​

While I was considering shifting to a code-based solutions, the source repo created a CLI to reveal its features. That was exactly what I needed: a dependable input to my process.

The AI SDKs had also progressed, so instead of regex and a script, I switched to .NET and the OpenAI SDK for chat completions. This time I designed the process deliberately, and Copilot Chat in VS Code was available, which helped accelerate development.

This time the architecture, project structure, maintainability, and testability were top considerations as I was still relying on this thing to help me.

There were a few iterations of this but it was beginning to hum along.

Stage 4 - the infrastructure​

Since I only had the OpenAI resource in Azure, I kept it live and never shut it down. However, I used keys instead of managed identity—not because I didn't know the best practices, but simply because I lacked the time to implement them.

I was doing a lot of Bicep work, not an expert but not a newbie either, so cooking up the ./infra and azure.yml for Azure Developer CLI wasn't hard. Adding the RBAC roles for managed identity helped. And then finally I had that repeatable infrastructure I told everyone else they should have.

Stage 5 - monkey on the keyboard​

The underlying project repo had matured significantly, the source code had stabilized, and my system was working well for its purpose too. However, as AI slop became an industry term, the underlying project matured alongside the industry specs it supported but my project had not.

I managed the project in chat one turn at a time, and the .NET app generated the output. However, every change to the system required several to many turns, redirections, and re-runs. AI kept making the same mistakes, and I spent my time minute by minute watching the output to see when it went off track. I needed a better process—a process to manage the process.

Stage 6 - hiring a squad​

It was around this time I started working with Brady Gaster's Squad. Having a team of agents accelerated progress and caught issues and inconsistencies I hadn't been able to spot before. I onboarded Squad to the repo and had them take on much of the work.

Stage 7 - industry grows up​

While I was learning Squad's inner workings, SKILL.md and agent.md specifications emerged. I dug into skills first to impose structure on my manual process management. I used WAZA and other frameworks to understand context size, triggers, and evaluations.

Building and maintaining skills locally gave me practical understanding of task boundaries, debugging, and chaining. Working with these units of AI many times a week gave me opportunities to fail.

Stage 8 - leaving Squad behind​

Squad is an amazing build and maintenance platform. However, I need skills that succeed independently. The plugin specification is now available, so I took my chained skills, wrapped them in an orchestrating agent to manage gates between skills and human review, and packaged everything as a plugin.

Stage 9 - the agent and the app​

What about the .NET app? It's now used only when the agent determines it needs that full pipeline. The agent and skills handle most of the work.

Conclusion​

You'll likely continue to hear a lot about AI slop. Just like any industry, AI is maturing and developing better specifications and expectations. Look for them and try them out.

Focus on the fundamentals available at the time. Build with principles and practices that support them. Grow with industry specifications that enable better results.

Writing the History of Software

· 8 min read

I have several projects I periodically update now as the sole maintainer. A few are projects I was on from the beginning, so I know the journey they took. One or two are new to me, and the people who carried that history are gone, changed roles, or told me to figure it out. I have the source code. I have the repos. I have all the commits. The source code should speak for itself.

But is source code enough to explain the choices inside it?

This is where I find myself as the project list grows and the maintenance load grows with it. How do I tend this garden of projects without losing the story of why each one became what it is?

The problem​

This issue of a better way to tend my garden of projects used to feel casual and theoretical. Now it is immediate. It starts with knowing what is in the source code, but not in some general way and not in some grep/regex way. I need a true, deep understanding of the choices, consistencies, and inconsistencies. Together, they should form the history and choices as well as the current state. From that, I can move forward with changes that do not impair or detract, or worse, unknowingly change the purpose of the project.

Woman at a crossroads holding the project book, ready to choose the path forward

An opportunity to write the history​

There is a lot of software out there to help with this brownfield problem space. People come and go in the industry so companies have no choice but to figure it out. There are a few problems the solution would have to tackle but understanding how to determine the guiding principles from the in-the-moment choices is the key. It is similar to determining a book's theme from its scenes and characters.

There are many vector-based solutions that can gobble up the source code, commits, comments, issues. From there you can begin to build the guiding principles and choices.

I turned to AI to help me figure this out and one of the answers pointed me to spec-kit. There is enough internal chatter at Microsoft that I had heard of it before. After comparing options, pairing it with my multi-agent orchestrator (Squad), and looking through a brownfield lens, I had a path forward.

Two steps back​

I can use something like spec-kit brownfield extension to come up with the main artifacts, then supplement with Graphify queries to solidify the details of the current state. This may seem like a lot of work, but with agents and skills, this process is quickly completed.

The project book, as a living artifact, should now be ready to review. It becomes the reference guide, the map that ensures every decision keeps the project on track. It should include:

  • Guiding principles - general design, stack and architecture
  • Features - what the project does and did
  • Core team - who they were, what they cared about, what they put off to a future state
  • Edge cases - the bugs reported, the features not quite complete, the dependencies that haven't aged well
  • Concerns - what are the features or class of bugs that need to be immediately reviewed and fixed

As more and more repos are created and many more are abandoned or in maintenance mode, the tools and skills to come into these projects quickly and move fast to understand and prioritize future work without disrupting current state will be important.

At this point in the process, the book is reviewed and the next steps are decided. How do I build using the book?

Relying on the team​

I've been using Squad, my team of agents, for so long I can't imagine working without them. They know my own style, choices, and history. They just don't know this new-to-me brownfield project. For this journey on the project, the book is the rules, the road, and the map. My team is the car keeping the project on the road, safely, to get to the next stop on the journey.

Squad has its own history it keeps in decisions, identity, ceremonies, and project context.

The squad has an architect that will manage the book and decide what stays in the Squad and what moves to the book. This is where things can get muddled. And they do in real life. The real-life architect has a push and pull with the engineering team.

Woman at a workbench, carefully sorting decision cards between two containers: one for Squad's operational memory, one for the book's institutional memory

To keep that from becoming chaos, I've started using a few simple guiding principles that create clarity without argument:

  • If it explains why we made a decision, it goes in the book.
  • If it is a temporary way to get through this sprint, it stays in Squad.
  • If a new maintainer would need it to avoid breaking something important, it goes in the book.
  • If it changes every week, it stays in Squad.
  • If it crosses feature boundaries or affects architecture, it goes in the book.

Another way I think about it: Squad is operational memory, the book is institutional memory.

Squad should carry the active context for doing the work today. The book should carry the durable context that keeps the work safe, consistent, and grounded.

When I'm unsure, I run a quick test:

  • Will this still matter in 90 days?
  • Does this capture a non-obvious tradeoff?
  • Would I want this during an incident review?

If two of those are yes, it gets promoted to the book.

That gives the architect and the team a shared rule. Less opinion. Less tug-of-war. More forward motion.

Extending beyond source code​

The more I do this, the more obvious it becomes: the software story does not live only in repos.

Some of the most important decisions happened in Teams or Slack threads, in meeting transcripts, and in docs that never made it to a pull request. If I only consider code, I get implementation detail. If I include communication and docs, I get intent. This is where the real story emerges.

That means the same book pattern should expand to include:

  • Communication history: decision threads, approvals, reversals, and unresolved debates.
  • Meeting artifacts: transcripts, notes, action items, and who agreed to what.
  • Non-code documentation: design docs, runbooks, incident reviews, architecture diagrams, and policy docs.

The same promotion test still works, just with broader sources.

  • Is this a durable decision?
  • Is this the reason behind the implementation?
  • Would future maintainers need this context to make a safe change?

If yes, it belongs in the book, even if it came from chat and not code.

In practice, I think of this as building a project memory graph, not a code index. Code tells me what exists. Conversations and docs tell me why it exists.

That is the difference between replaying commits and understanding a system.

Operationalizing this​

I needed this to be more than a good idea, so I turned it into a repeatable weekly practice. This is where theory becomes practice, where chaos becomes system.

This pattern is bigger than any one product. It fits a growing class of brownfield context tools that turn scattered project signals into usable memory.

  1. Gather sources in a fixed order.
  2. Extract candidate decisions, tradeoffs, and unresolved risks.
  3. Score each item with the promotion test.
  4. Promote what is durable to the book.
  5. Keep execution-only context in Squad.
  6. Review drift and stale entries on a schedule.

For source priority and trust, I use this order:

  1. Decision records and architecture docs.
  2. Incident reports and postmortems.
  3. Meeting summaries with named owners.
  4. Pull requests and issue threads.
  5. Chat threads from Teams or Slack.

Higher-ranked sources are usually cleaner on intent and accountability. Lower-ranked sources still matter, especially when they are the only place a decision was captured, but they need corroboration.

To keep this light, I timebox it.

  • 30 minutes a week for promotion from Squad to the book.
  • 30 minutes a month to prune stale context.
  • 60 minutes each quarter for architecture drift review.

That rhythm gives me a stable memory system without turning documentation into a second full-time job.

Further reading: workflows like Scout, OpenClaw, and similar brownfield context systems can support this pattern.

Summary​

I started with a simple question: should source code be enough? For brownfield work, my answer is no.

I treat source as evidence, not the whole story. The story gets written in the book: principles, tradeoffs, features, edge cases, and the things the original team quietly knew.

Squad helps me move quickly through current work. The book keeps that work safe, consistent, and grounded.

When those two stay in sync, maintenance stops feeling like archaeology and starts feeling like stewardship. That is how I keep momentum without losing meaning.