👉 To read this post for free (and without paywalls), visit: https://www.wesleymatlock.com
If you’ve already spent time with Claude Code hooks, plugins feel like the next logical step - and also like a completely different animal.
Hooks are reactive. Something happens, you respond.
Plugins are intentional. They encode how work should happen.
That distinction didn’t fully click for me until after attending the AI Symposium 2026 at the US Space & Rocket Center. A lot of the conversations there weren’t about models getting smarter - they were about agents, automation, and safety. Not in an abstract way, but in a very real “what happens when this runs unattended?” way.
Claude Code plugins sit right in that tension.
This post isn’t a victory lap or a polished “best practices” guide. It’s a snapshot of what I’ve learned so far - what feels powerful, what feels dangerous, and where I’ve had to slow myself down and rethink how I approach automation for iOS teams on macOS.
If you’re already using Claude Code locally and thinking about scaling those workflows across a team, this is the layer where things get interesting.
👏 If this kind of deep-in-the-weeds tooling write-up helps you, give it a clap so I know to keep going.
Series: AI Tooling for iOS Teams
This post is part of an ongoing series exploring practical AI workflows, automation, and guardrails for iOS teams working on macOS.
🔄 Plugins Changed How I Think About Claude Code
When I first started using Claude Code, it felt like a smarter terminal assistant. Useful, but still reactive.
Plugins flipped that.
A plugin isn’t just a skill you can invoke. It’s a bundle of behavior:
- skills (commands you can invoke)
- agents (specialized subagents for specific workflows)
- hooks (automation points)
- configuration (scope, lifecycle, and limits)
- and eventually, distribution
Once you internalize that, the question stops being “What can Claude do for me?” and becomes:
“What behavior am I encoding - and who does it affect?”
That framing matters a lot more for teams than it does for solo devs.
🧠 The Mental Model That Finally Stuck
Here’s the mental model that helped me stop misusing plugins:
- Hooks are events
- Skills are tools
- Agents are specialized subagents
- Plugins are policy
That last one is the big shift.
When you install or commit a plugin, you’re not just adding convenience - you’re making a statement about:
- how code should be reviewed
- how changes should be described
- what “safe” looks like
- what automation is allowed to touch
That’s why plugins feel heavier than hooks. They should.
🛠️ Why This Matters for iOS Teams (Especially on macOS)
iOS teams already operate inside layers of implicit rules - architectural patterns, formatting expectations, release rituals, CI assumptions, and security constraints that shape how work gets done long before code ever ships.
The problem is that most of these rules don’t live anywhere executable. They’re scattered across README files nobody rereads, onboarding docs that age out of relevance, and tribal knowledge that only surfaces during code review - usually when it’s already a little too late.
Claude Code plugins give you a way to turn those expectations into something tangible. Not more documentation, but lightweight tooling that reinforces how the team wants to work while the code is still local and malleable.
On macOS, this lands especially well. The terminal is already a first-class part of the iOS developer workflow, Xcode is deeply scriptable, and most decisions happen locally long before CI ever gets involved. Plugins fit naturally into that gap.
The real value isn’t replacing reviews or automating merges. It’s shaping behavior earlier - nudging consistency, surfacing risk, and reducing entropy before changes ever leave a laptop.
🌱 Plugin Scope: Personal vs Team Is the First Fork
One of the earliest mistakes I made with Claude Code plugins was treating them all the same. That assumption doesn’t survive first contact with a team.
Plugins can be installed at different scopes, but the important distinction isn’t technical - it’s cultural. A personal plugin and a team plugin may look identical on disk, but they carry very different expectations.
Personal or local plugins are where learning happens. This is the space for experimentation, rough edges, half-formed ideas, and prompt tuning. You’re free to move fast here because the blast radius is small. If something feels off, you delete it and move on. That flexibility is part of the craft.
Team-scoped plugins are a different bar entirely. The moment a plugin is committed to a repository or shared across a group, it stops being an experiment and starts behaving like infrastructure. Naming matters. Versioning matters. Rollback matters. Most importantly, intent has to be obvious to anyone who didn’t write it.
A team plugin isn’t just automating your workflow - it’s shaping everyone else’s. That’s the fork in the road. Choosing when to cross it deliberately is one of the most important decisions you’ll make when scaling Claude Code beyond yourself.
🧩 What We’re Going to Build (Conceptually)
Rather than jumping straight into isolated examples, I want to ground the rest of this post in a single, coherent workflow - the kind of setup you might actually recognize from a real team.
The examples that follow are framed around a fictional, but intentionally realistic, iOS app inspired by themes that came up repeatedly at the AI Symposium: aviation, safety-first thinking, and predictable operations. The point isn’t the domain itself. It’s the mindset that comes with it.
Imagine a team that values clarity over cleverness. Releases are deliberate. Automation is welcomed, but only when its intent is obvious and its behavior is conservative. Surprises are treated as failures, not features.
Using that backdrop, we’ll walk through how a simple Claude Code plugin comes together - how skills and an agent fit into a workflow, where it makes sense to automate, and just as importantly, where it doesn’t. Along the way, we’ll look at the kinds of failures you’re likely to hit and how to reason about them when they happen.
Everything here runs locally on macOS and assumes you’re already comfortable living in the terminal. The goal isn’t to build something impressive. It’s to build something you’d actually be willing to keep around.
⚠️ A Note on Agents and Safety (Before Code)
One thing the Symposium reinforced hard: agents amplify intent.
That’s exciting - and dangerous.
In Claude Code, agents are specialized subagents designed for specific workflows. Unlike one-shot skills, agents are architected to handle ongoing responsibilities within a domain. This creates a different feeling when you work with them - they’re designed to maintain context across related tasks within their specialized area.
If you wouldn’t trust a junior engineer to do it unsupervised, don’t hand it to an agent yet.
🧱 Defining a Minimal Plugin (No Cleverness Yet)
Claude Code plugins follow a specific directory structure. Skills and agents are separate files, not defined inline in JSON.
Here’s the complete structure:
flight-safety-tools/
├── .claude-plugin/
│ └── plugin.json
├── skills/
│ └── review/
│ └── SKILL.md
└── agents/
└── release-guard.md
The Plugin Manifest
{
"name": "flight-safety-tools",
"version": "0.1.0",
"description": "Local tooling to keep iOS changes predictable and reviewable"
}
The Review Skill
---
description: Review recent changes with a safety-first lens
disable-model-invocation: true
---
Review the recent git diff focusing on:
- Risk and unintended side effects
- Clarity of intent
- Potential edge cases in the changes
The Release Guard Agent
---
description: Ensures release notes are explicit and conservative
---
When preparing a release, verify that:
- Changes are clearly described
- No risky behavior is implicit
- All modifications are explicitly documented
Nothing fancy - and that’s intentional. This plugin isn’t designed to mutate code, auto-run in the background, or quietly change behavior behind your back. Its job is simpler than that.
It exists to nudge. To surface intent at the right moment, reinforce conservative defaults, and then get out of the way. That kind of restraint isn’t an accident; it’s the whole point.
🔥 Skills vs Agents (Where People Get Burned)
The difference between skills and agents sounds subtle on paper. In practice, it’s where a lot of people get themselves into trouble.
Skills are explicit by design. You invoke them intentionally, usually with a clear goal in mind, and they do exactly one thing before getting out of the way. They feel like tools - you pick them up when you need them, and you put them down when you’re done.
Agents feel different.
Note: This describes the conceptual experience of working with agents, not the literal implementation. Agents in plugins are specialized subagent definitions that can be invoked through Claude Code’s agent system.
The first time I added an agent, the shift was immediate. It wasn’t about raw capability - it was about presence. Agents are designed around ongoing responsibility. They carry context, they influence a sequence of related tasks, and they invite you to lean on them more than a one-shot skill ever would.
That’s where the risk creeps in.
An agent should exist for a narrow, well-defined purpose. It should be intentionally boring, conservative in its behavior, and loud when something feels off. The moment you feel tempted to let an agent “just handle things automatically,” that’s usually a signal to stop and rethink the design.
Skills help you move faster. Agents shape how you think about the work. Mixing those two without care is one of the fastest ways to erode safety without realizing it.
🧪 Debugging When (Not If) Things Break
You will hit issues. Here are the common ones I’ve run into:
Plugin Not Loading
- Check
plugin.jsonsyntax - Restart Claude Code
- Look at the Errors panel - it’s usually honest
Skill Namespace Confusion
Skills are namespaced using the plugin name:
/flight-safety-tools:review
If it doesn’t autocomplete, it probably isn’t registered.
Agent Doing Too Much
This is a design problem, not a bug.
Reduce scope. Remove memory. Make it dumber.
Path & Cache Surprises
Installed plugins are copied into Claude’s internal plugin cache (for example, under ~/.claude/plugins/cache/).
Do not rely on relative paths outside the plugin directory (like ../shared-utils), as those files won’t be included when the plugin is installed or cached.
📏 Rules of the Road (Non-Negotiable)
For team plugins:
- ❌ No auto-commits
- ❌ No silent edits
- ❌ No destructive actions
- ✅ Version everything
- ✅ Review plugins like code
Plugins are infrastructure. Treat them that way.
🚀 Still Learning, Still Shipping
Claude Code plugins feel like an early chapter, not a finished system.
Agents are improving. Governance is coming. Marketplaces will mature.
For now, the responsibility sits with us - to automate carefully, to encode intent clearly, and to remember that safety scales slower than power.
That’s not a limitation. It’s a feature.
🏪 Marketplace & Discovery (Why I’m Not Publishing Yet)
Claude Code supports plugin discovery and marketplaces, and on paper, that’s exciting. Shared tools. Reusable automation. A growing ecosystem that can move ideas quickly between teams.
But this is one area where I’m being intentionally slow.
Publishing a plugin - even internally - is a form of endorsement. It signals that a workflow is stable, that its behavior is understood, and that its automation is safe enough for other people to adopt without context. Most plugins don’t start their lives in that state.
Right now, many of the plugins I’m experimenting with are still evolving alongside the tooling itself. They’re shaped by trial and error, revised as edge cases show up, and occasionally removed when something that felt helpful stops feeling safe. That’s not something I’m comfortable packaging up and handing to others yet.
For iOS teams, I’ve found it healthier to think about distribution as a progression rather than a switch you flip. Start locally, where experimentation is cheap. Move to project-scoped plugins once behavior stabilizes and intent is clear. Only then does it make sense to think about an internal marketplace with shared ownership. Public distribution should come last - and only when the automation is boring, predictable, and unlikely to surprise anyone.
Skipping those steps might feel efficient, but it usually just defers the hard conversations. Governance doesn’t magically appear when you publish. It has to exist first.
😬 An Agent That Almost Went Too Far
At one point, I experimented with an agent that watched changes during release prep and proactively suggested updates to release notes. On paper, it was exactly the kind of thing agents are supposed to be good at.
And technically, it worked.
The problem wasn’t accuracy. It was timing. The agent started inferring intent before I had fully formed it. It nudged language earlier than I was ready for. Over time, it introduced a subtle pressure to accept its version simply because it was already there.
Nothing was objectively wrong with the output. But the experience felt off.
That’s when something important clicked for me: good automation should reduce cognitive load, not create social or psychological pressure. The moment an agent starts shaping decisions instead of supporting them, it’s crossed a line - even if everything it’s doing is technically correct.
That experiment never left my local machine. I tore it down, not because it failed, but because it succeeded in a way I wasn’t comfortable with. And that distinction matters.
🏛️ Governance Is Coming - Don’t Wait for It
It’s obvious that governance models are coming to this space. Permissioning, auditability, policy layers - all of that will arrive eventually, and when it does, it’ll be welcome.
But waiting for a framework before developing judgment is backwards.
Right now, the most effective guardrails aren’t technical at all. They’re human decisions made early and reinforced consistently. Conservative defaults. Explicit invocation. Clear, visible intent. And the willingness to delete automation that no longer feels safe or appropriate.
Plugins make it trivial to add power. They do almost nothing to help you take it away.
That imbalance is why governance can’t be something you outsource to future tooling. It has to start with how you design plugins today - what you allow them to touch, how loudly they communicate intent, and how easy they are to roll back when something doesn’t sit right.
If you build with that mindset now, formal governance later becomes an extension of what you’re already doing - not a reaction to something that quietly got out of hand.
✍️ Final Thoughts (Still in the Early Chapters)
Claude Code plugins don’t feel finished - and that’s a good thing.
They reward restraint and punish cleverness in equal measure. They surface assumptions you didn’t realize you were making about automation, responsibility, and where control should live. You find those edges quickly, sometimes uncomfortably, and that feedback loop is part of what makes the tooling valuable right now.
For iOS teams on macOS, plugins are already useful today - not because they replace engineers, but because they make expectations executable. They help clarify intent earlier, reduce unnecessary variance, and expose risk before it has a chance to hide behind momentum.
I’m still learning where those boundaries should be. I’m still removing things that felt smart a week ago but don’t feel safe anymore. And I’m still approaching agents with more suspicion than excitement - not out of fear, but out of respect for how much influence they can quietly accumulate.
This space is moving fast, and it will mature. When it does, I want governance to feel like a natural extension of good habits already in place, not a reaction to automation that outpaced judgment. That’s the mindset I’m trying to build with - one plugin at a time.
🎯 Bonus: More Real-World iOS Survival Stories
If you’re hungry for more battle-tested Swift, SwiftUI, and tooling stories - including AI workflows that actually ship - you can find the rest of my writing here: