DEV Community: Fabrizio

Claude Code Plugin Marketplace: One Setup for a Whole Team

Fabrizio — Tue, 20 Oct 2026 06:05:00 +0000

Claude Skills are the easiest thing in the world to write. A text file, four lines of instructions, and Claude can do something it couldn't do before.

And the best part? You don't even write it yourself. There's a Skill whose only job is writing Skills: you say what you need, it asks two questions, and it hands you something ready to use. Claude writing its own instructions.

There are thousands to download. Curated, free, ready.

Then you write one yourself. A real one, shaped around your work and your clients. And the most natural urge in the world follows: share it with your team.

That's where the trouble starts.

What you need to get started

Before the how, let's clear the question that blocks everything else: what it costs to be in a position to do this at all.

A Cloudflare account. Free. That's where the server runs and where the credentials live.
A GitHub account. Free. It's the distribution channel — and it's also the login, which is what makes it possible to tell users apart.
A Claude subscription (or another coding assistant) to write the server code. You probably have that one already if you've read this far.

No infrastructure to buy. No enterprise plan to activate. No vendor to call.

For a team of three, the bill is zero per month. The real cost is one afternoon.

How we got into this mess

I'll tell you how it started, because that explains the problem faster than any definition.

You start your company. You're fired up. You work for one client, then another, then you spend two days fixing your own website. Your partners do roughly the same.

At the end of the day you open Kimai — the tool we use to assign hours to projects — create a timesheet, and write down that you spent two hours on one thing and four on another.

You do it once. You do it twice… by the third time you feel like a caveman.

You work with AI for hours every day, and in the evening you do manual data entry like it's 2010?

Unacceptable.

So you open the Kimai API docs and in half an hour you build your own tool: from now on you dictate the hours to the agent and it enters them for you.

Deeply satisfying.

Then you hand it to your partners. And here you make the first wrong move without noticing: you write the exact same code three times, one per person, because each copy needs the right user id inside it — otherwise Otoni's hours end up under my name.

A month goes by. You add Matomo to watch traffic on the site. You build the stats tool, wire it into Claude, works beautifully.

Then you try scheduling a task that sends them to you every Monday morning.

And it stops working.

Why? Because scheduled tasks run in the Cowork sandbox. And the sandbox can't see that tool. And while we're at it, neither can Claude Code. Same machine, same person, three separate boxes that don't talk to each other.

Meanwhile, where's the Matomo token? In plaintext, in a file on your laptop.

So what do you do? You write a Skill with the token inside it and pass it to your partners. Great — now everyone can ask Claude how the site is doing.

Except that token is now sitting in plaintext on three different computers.

Cybersecurity: outstanding.

And your diseased developer brain doesn't stop there. The SEO tool. The one that generates PDFs in the Arkad brand. The one that scans client sites. One after another.

A few weeks later you look back and find this: a mess of Skills, with tokens in plaintext inside them, working in one environment and not another, in different versions between you and your partners.

Following me? That's the point where I stopped and thought about an actual solution.

Five obstacles on the table:

Distribution — how my Skills reach my partners.
Updates — how they know whether they have the latest revision.
Secrets — where I put a token without scattering it around.
Portability — how I make it work in three environments that don't talk to each other.
Identity — how the server knows which of the three is using it.

One at a time.

What Claude Skills are (and why they're not an MCP server)

We need a distinction. It's the one that unlocks everything else.

A Skill is a text file with instructions. It tells Claude how something is done: which procedure to follow, in what order, with what care, what never to do. It executes nothing. It's knowledge, not hands.

An MCP connector (Model Context Protocol) is the opposite. It's a service exposing executable functions. It explains nothing: it does. It queries a database, calls an API, writes to a CRM.

Skills instruct. Connectors act.

It sounds like a textbook subtlety. It's actually the key to the whole thing: the two travel together but must be kept apart — and further down you'll see that this separation is exactly where the context savings come from.

Above both sits the container. A plugin is a package holding Skills and connectors as one versioned unit: you install it with one command and update it with another.

Skills and connectors are the parts. The plugin is the box you ship them in.

The same plugin on Claude Desktop, Claude Code and Cowork

I'll start with the most painful problem, portability, because the fix is almost embarrassingly simple.

A remote MCP connector doesn't live on your computer. It lives on a server — in our case a Cloudflare Worker, free well past volumes three people couldn't hit by accident.

And because it lives on the internet instead of in your user folder, every environment sees it the same way.

You connect it in Cowork and find it identical in Claude Code. You open the desktop app and it's there. Scheduled tasks find it. And since the protocol is open, that same server can be used by any other client that speaks MCP — ChatGPT, for instance.

I didn't solve the problem by configuring the three environments better. I solved it by moving the thing to be configured out of all three.

First obstacle down. ✊

Secrets and OAuth: where the tokens actually live

The second one falls almost as a consequence. But it's worth a close look, because it's the one a cautious client will actually check.

If the server sits on Cloudflare, you upload the Matomo token once, as a Worker secret. From then on it lives there: encrypted, off the laptops, out of the chats, out of the mailboxes. None of my partners has ever seen it. And none of them needs to.

When I rotate it, I update it in one place. There are no other places to pull it from, because it was never anywhere else.

So how do the partners get in, if they don't have the token?

With OAuth. The server asks whoever connects to identify themselves and hands back an access of their own — traceable, individually revocable. It's the same mechanism you use when you sign into an app with your Google account.

I'd sum up the difference like this: the secret isn't kept in three copies, it's written once and for all on the server.

Second obstacle down. High five 🖐️

Hey server, it's Fabrizio: the identity problem

Now the part nobody talks about, and in my view the real reason to build your own MCP server.

Every vendor has a connector these days. Google Drive has one. Gmail has one. Notion has one. A new one ships every week. So why write your own?

Because the official connector solves the easy case: its service, your account, one at a time. Outside that, three cases are left uncovered — and they're the ones I ran into.

The connector doesn't exist. Your internal tool, the script you wrote against some back-office API, the database at home: no vendor will ever write the connector for your own tool.

You need two accounts of the same service. Right now each connector holds one: you connect your Gmail and the company's contact@ mailbox stays out in the cold.

Upstream there's a single key for everyone. Access works fine, but the system on the other side sees one user for the whole team. Access is solved. Who you are isn't.

Take Kimai, the system we track client project hours in. The server has an admin token: one key, very powerful, able to write anyone's hours. Convenient for the server. Useless for us.

Because if I log three hours on a project, those three hours have to show up under my name. Not under the partner who set up the token first. Not under a generic "Arkad" user.

It's called traceability. Without it, the hours ledger is worthless: you don't know who did what, you don't invoice accurately, you can't see where the team's time is going.

How is this usually solved? Badly. Three separate API keys, one per partner, each to store, each to rotate, each to reconfigure in three environments. Back to square one, times three.

The clean path we chose: everyone authenticates with their own GitHub account, inside a GitHub organization only we have access to.

The GitHub organisation: whoever is in gets in, whoever leaves loses access to everything in one click.

Two things follow from that:

The wall. Only members of the organization can use the connector. Whoever isn't in doesn't get in — and the day someone leaves the team, you remove them from the organization and they've lost access to everything. One move, not a hunt for scattered keys.
The name. The server knows who you are on every call. So when I log hours I don't have to tell it I'm Fabrizio: it already knows, and it puts my name in the right place by itself.

Not one of us three holds a Kimai API key. We don't need one. We authenticate once with GitHub and the server does the rest, knowing exactly who asked for what.

And since you're writing the server anyway, you pick up a second advantage. A vendor's official connector brings forty tools and broad permissions into your context: you load them all, always, even when you use two. Yours exposes six, read-only, with the rules written server-side. Less context spent — more on that below — and a much smaller surface to defend. For a cautious client that isn't a technical detail: it's a sales argument.

Third obstacle down.

Here, roughly, is what our MCP authentication setup looks like.

One server. Three people, whichever client they prefer, their own GitHub account at the door — and keys that never leave Cloudflare.

Installing the plugin from a GitHub marketplace

That leaves distribution and updates, which are the same problem seen at two different moments.

The answer is a GitHub repository set up as a marketplace: a registry listing the available plugins. Everything lives inside it: the catalog, one plugin per tool family, and — since we merged the two repos — the Worker code as well. Skill and tool change in the same commit.

We're not alone in this. Thoughtworks put the Claude Code plugin marketplace on its Technology Radar for exactly this reason: sharing custom commands, agents, MCP servers and skills used to be manual copy-paste out of Confluence, which left team members running outdated instructions, and their teams now distribute those artifacts through the marketplace with a Git-based model, hosting internal marketplaces on GitHub. Same disease, same cure — they just wrote it down before we did.

arkad-marketplace/
├── .claude-plugin/
│   └── marketplace.json      # the catalog: name, owner, list of plugins
├── plugins/
│   ├── arkad-documents/      # Skills-only plugin: no MCP, no secrets
│   │   └── skills/arkad-documents/
│   │       ├── SKILL.md
│   │       └── assets/       # templates and logos ride inside the Skill
│   └── arkad-tools/          # plugin with a connector: one MCP server, ten Skills
│       ├── .claude-plugin/
│       │   └── plugin.json   # name and version — the version is the release switch
│       ├── .mcp.json         # four lines: type http and a URL. No token.
│       └── skills/           # arkad-connect, arkad-seo, arkad-kimai…
├── arkad-tools.plugin        # the plugin zip: this is how Cowork installs it
└── gateway/                  # the Cloudflare Worker, in the same repo
    ├── src/index.js          # the OAuth wrapper around the MCP handler
    ├── src/github-auth.js    # GitHub login and organization allowlist
    ├── src/mcp.js            # JSON-RPC: initialize, tools/list, tools/call
    ├── src/tools/            # one file per family: matomo, seo, kimai…
    └── wrangler.toml         # the KV binding and the list of secrets

Note arkad-documents: no .mcp.json. It's instructions and templates only, it touches no system — and it therefore costs nothing in context until you invoke it.

A partner adds the marketplace once and installs the plugin. From then on the cycle is this: I edit a Skill, fix the code, push to GitHub. He runs the update and has the latest version. All the Skills, the connector, everything together. Without me sending him anything.

The version number isn't decorative: it's how Claude Code knows there's something new to fetch.

And since it's all on Git, the history of changes stays. You can see who changed what.

Last two obstacles down together.

After a few months of real use, the compound effect is this: nobody asks how did you configure yours? anymore. The question stopped making sense.

We also dropped the other habit: sending each other files over WhatsApp, because that's where we talk. One of us downloaded it, the other didn't. Three weeks later the one who hadn't would message you that the download had expired and he needed it again — and by then you were already on version six.

There's one plugin, one version, credentials that belong to each person, Skills written once, and an agent that uses the tools correctly without anyone explaining anything to it.

MCP isn't dead: the real context cost

Here comes the objection. And it always arrives with a certain confidence: MCP is dead, it eats context, we use Skills now.

There's something to it. A connector loads its tool descriptions into the context window at startup. Always, whether you use them or not. A Skill only loads when needed. On that point, whoever says it is right.

But that's a long way from dead.

Context consumption is a consequence of how you write the descriptions. The whole trick is right there.

Keep MCP tool descriptions to the bare minimum: what the function does, what parameters it takes, full stop. Everything else — when to use it, in what order, how to read the result, which errors are normal — goes into a Skill in the same plugin, which loads only at the moment it's actually needed.

Done that way, my plugins sit at around 1% of the context window. You can measure it yourself with a plain /context in Claude Code.

One percent for direct access to my systems from any environment isn't a price. It's a rounding error.

What holds for three partners, and what will change

One last thing, because I don't want to sell this architecture as more than it is.

GitHub isn't the answer. It's our answer.

We picked it for a mundane reason: there are three of us, we all already had a GitHub account and an organization of our own where we keep our projects, so there was nothing to create and nothing to explain. But the Cloudflare server is configured exactly the same way with Google, or with any other identity provider the company already uses.

The pattern isn't "use GitHub". The pattern is: lean on the directory you already have, whatever it is. The day someone who doesn't write code joins, or the day we install this architecture at a non-technical client, GitHub is the wrong choice and Google Workspace is the right one. The provider changes, the design doesn't.

And then there's an honest limitation to state.

Today we all have identical permissions: any of us can use any tool. So the server only needs to know one thing, who you are, and it knows it. That's plenty.

The day we give access to an employee, it won't be. We'll need roles defined on the server, each role mapped to a set of tools, and a role assigned to whoever connects based on their position in the organization. Whoever holds the right role sees that tool, the others don't.

Things will get more complicated. I'm not hiding it.

But that's a problem we'll have when we have it. Meanwhile this has genuinely changed how we work, and in this field everything moves so fast that the only sensible promise is that one: when it needs to change, we'll change it.

In short

Skills are easy to write and impossible to keep in sync by hand across three copies.
Skills and MCP connectors aren't the same thing: the first instruct, the second act. Keeping them apart is what lets the context breathe.
A remote connector is visible the same way from Claude Code, Cowork and scheduled tasks, because it lives on none of the three.
Secrets stay encrypted on the server, in one place. Each person authenticates on their own behalf.
GitHub organization auth buys two things at once: everyone outside the team stays out, and the server knows the name of whoever is calling. No more one API key per partner.
A GitHub marketplace pushes every update to the whole team with one command, and keeps the record of who changed what.
MCP isn't dead. In a well-kept plugin it costs about 1% of the context window, and it buys the one thing Skills alone can't give you: the ability to act.
GitHub is our instance of the pattern, not the pattern: Google or any existing company directory works just as well. And as long as permissions are identical for everyone, identity is enough; with an employee you'll need roles.

It takes one afternoon. It takes two free accounts.

And then you don't go back.

Enjoy the afternoon. See you around 👋

Arkad Consulting helps teams and companies put AI into production without the hype: from internal agents to shared Claude Code plugins. Let's talk.

Originally published on arkad-consulting.com.

Get Serious About AI: Start Here

Fabrizio — Mon, 08 Jun 2026 11:37:49 +0000

How an AI actually thinks

Tokens: the hidden unit of measure

When you type to an AI, it doesn't read words. It reads tokens — little chunks of text. A token might be a whole word ("house"), part of a word ("intelli" + "gence"), or just a punctuation mark.

«I think I am»: each colour is a token.
So why chop text up like this instead of just working with whole words?

Because if the model only knew whole words, anything it hadn't seen before would trip it up — a typo, a name, a technical term, a foreign word. Anything outside its vocabulary would just stop it. But with fragments, it can build even words it has never seen from pieces it already knows. That's why it still understands you when you type in a hurry and your words come out wrong! 😉

So why not go all the way down to single letters?

Because the smaller the unit, the more tokens it takes to say the same thing, and the model's workload grows fast — double the tokens and you don't double the effort, you blow it up. The token is the sweet spot: big enough to stay efficient, small enough to never panic in front of a new word.

In AI, everything is counted in tokens — what you write and what the model writes back — and those tokens are what you're billed on, incoming and outgoing alike. It's not a technical footnote. It's the unit you measure work and cost in.

The cost of models: why two similar answers can cost different amounts

Every model has its own price, usually quoted as cost per million tokens. And here's the first surprise: ask the same question of two different models and one can cost twenty times more than the other.

More powerful models are more expensive to run, so they cost more per token: a lightweight model runs you a few cents where a top-tier one charges a few euros. Which leads to a practical rule — you don't always need the most powerful model. To summarise an email or sort incoming requests, the lightweight one does the job beautifully at a fraction of the price. Save the expensive one for real reasoning: a tricky analysis, sensitive code, a piece of writing that has to be flawless. Matching the model to the task is already half of cost control.

There's a second thing that weighs on the bill: input and output aren't priced the same. The tokens you send in — prompt, documents, conversation history — are the input. The ones the model writes back are the output, and they almost always cost more, often three or four times as much.

It comes down to where the effort goes. Reading your prompt is the easy part — the model takes it in all at once. Writing the answer is the real work: it produces one token at a time, and at every step it has to pick the next one while keeping everything it's written so far in mind. The energy goes into the writing, not the reading. That's why you pay more for output and less for input.

Context: the model's working memory

Context is everything the model has in front of it while it answers you: your question, the instructions, the documents you've handed over, and the back-and-forth so far.

Two things worth knowing. First, context has a ceiling — the context window, also measured in tokens. When it's big, you can drop in whole contracts or reports; when it's small, you have to be picky about what goes in. Second, and less obvious: you pay for the whole context, every single message. In a long conversation, every new line makes the model reread all the rest from scratch. That's why never-ending chats get slow and pricey — they drag a heavier and heavier load behind them.

Think of a desk. Context is the space on the table: you keep the documents you need right now in front of you. Pile it with junk and you work worse. Keeping it clear — giving the model only what actually matters — is a real skill.

So how big is the window?

Bigger every year. Next to a model's name you'll often see something like 1M — the window holds a million tokens, about as large as it gets today. That's hundreds of pages: in theory you could stuff whole documents or marathon conversations in there.

In the model selector, «1M» indicates the one-million-token context window.
In theory. Because having the room doesn't mean you should fill it: the more you load the context, the worse the answers get. Buried under thousands of lines, the model loses the thread of what matters — past roughly 300,000 tokens it starts slipping in accuracy and "forgetting" important things. It's a limit of today, one that'll ease as models improve, but for now you have to plan around it. The goal isn't to fill the window. It's to never get near the bottom.

In practice, two habits cover most of it:

Compact often. Work in stages: at each milestone, summarise where you've landed, start fresh from the summary, and drop the rest. A trimmed-down conversation runs far better than one hauling every line from the start. Some tools do it for you — ChatGPT and Claude manage the context behind the scenes, dropping the oldest messages as the chat gets long. Others, built for people who work in depth (Claude Code, for example), hand you the controls: you trigger the compaction yourself, with a command like /compact.
One topic per session. Different jobs, different chats. Don't use the same thread to draft a client email, clean up a spreadsheet, and then brainstorm ideas for a post — each topic leaves residue that muddies the next. Opening a fresh chat costs nothing, and it's almost always the right move.

Simple models and complex models: the difference that matters

We tend to think the most expensive model is the best one. It's more useful to picture them as a team with different roles.

A lightweight model is fast and cheap, great for well-defined, repetitive work: pulling out data, classifying, answering routine questions, banging out first drafts. Think of a sharp intern — hand it a clear task and it's done in no time.

A top-tier model is slower and pricier, but it holds up under real reasoning: nuance, ambiguity, problems with several moving parts. Think of a senior consultant — you pay more, but that's who you call when things get serious.

Knowing when to switch between the two — lightweight for volume, powerful for the hard knots — is exactly what separates someone who uses AI well from someone who just wings it.

Language or multimodal: what the model "sees"

The early models understood and produced text only — these are the language models. You write, they write.

Multimodal models handle several kinds of data at once: text, images, sometimes audio and video. Show one a photo of an invoice and it pulls the figures; hand it a screenshot of a chart and it tells you what's going on; give it a picture and it tells you what's in it.

One distinction worth getting straight: multimodal on the way in versus on the way out. On the way in means the model can take in more than text — photos, PDFs, audio, video. On the way out means it can produce them — not just write, but generate an image or a voice. Today's top-tier models (GPT-5.5, Gemini 3, Claude Opus 4.7) take almost anything on the way in; on the way out the capabilities vary a lot, so it's worth checking case by case.

A model card: Input accepts text and images, Output text only — multimodal on the way in but not on the way out.
A few acronyms show up here, worth decoding once and never looking up again:

STT (Speech-To-Text): voice in, text out. Automatic transcription — you talk, it types. You'll also see it called ASR (Automatic Speech Recognition).
TTS (Text-To-Speech): text in, voice out. The reverse route — you write, and the model reads it aloud.
Text-to-Image (sometimes TTI): text to image. You describe what you want and the model draws it — it's what powers tools like Midjourney and DALL·E.
Image-to-Image (img2img): image to image. You start from a picture and transform it — restyle it, touch it up, extend it past its edges.
If you're deciding what to automate, it boils down to one question: is your starting material text only, or are there images and visual documents in the mix?

Scans, photos, PDFs full of tables — you want a multimodal one. Text only — a language model has you covered.

The prompt that makes the difference

Most of the time, the gap between a mediocre result and a great one isn't the model. It's how you asked.

The prompt is the instruction you give the AI, and the quality of the answer tracks the quality of the request. A vague prompt ("write me something about marketing") gets you a vague result. A sharp one — with role, context, goal, format, and an example or two — gets you something you can actually use.

It's worth knowing, especially once you start using AI inside your own tools and not just in a chat box, that there are three types of prompt.

System: the ground rules — who the model is and how it should behave. Its role, its tone, the things it should always respect. It frames the entire conversation, and it usually stays hidden: in a ready-made app or assistant, the system prompt was written by whoever built it, and you never even see it.
User: what you ask, message by message.
Assistant: the model's own replies, which are part of the prompt too — with every new message it rereads what it already said as well.
In everyday chat these three types stay out of sight: you just type. But the moment you work through an API or configure your own assistant, understanding the difference is what lets you give it a steady identity (in the system), kept separate from each individual request (in the user).

Three habits that change the results straight away:

Be specific about context and goal. Not "write me an email," but "write a follow-up to an SME client who's gone quiet for two weeks — warm but direct tone, 120 words max."
Show an example. One sample of what a good result looks like beats a thousand explanations.
Iterate. The first prompt is a draft: you refine it, add a constraint, improve it pass by pass. Every small adjustment compounds.
Learning to prompt well isn't a trick for tinkerers. It's the single highest-return skill in the whole thing.

The tools you need

Understanding the concepts is half the job; the other half is the setup you work in. These aren't "programmer stuff" — they're the workbench of anyone who wants to build something serious with AI: scripts, integrations, small projects that last over time.

Git: the time machine for your files

Git tracks every change you make to your files. Each time you save a checkpoint (a commit), it takes a snapshot: you can roll back to any version, see what changed and when, and work on different ideas in parallel without breaking the one that already works.

Picture the version history on a shared document, but far more powerful and for any kind of file. The payoff isn't only technical — it's peace of mind, knowing nothing's ever really lost and every mistake can be undone.

But do you actually need it?

Fair question — Git can look intimidating at first — and the honest answer depends on how you work. If you're a freelancer working 90% of the time on your own machine, using Claude or another local agent for your files (projects, second brain, invoices), you probably don't need Git: a synced cloud drive (Google Drive, OneDrive, Dropbox) keeping an always-current backup is plenty. Simple, automatic, done.

Git earns its keep the moment more than one set of hands is touching the same files. You're working with a team on shared projects — local or in the cloud — and these days "the team" can include agents too.

Here's a real example from my own setup. Everything lands in my inbox: links, ideas, photos, quick notes. But it comes in through different doors — sometimes I jot it in the iPhone Notes app, sometimes I send a voice memo to an agent that transcribes it (STT) and commits the text straight to GitHub. So the same folder gets touched by my machine and by an agent writing from the cloud, sometimes within the same minute. Without Git to reconcile those overlaps and merge them without dropping anything, I'd be sunk.

So, the rule of thumb:

Working solo and just getting started with local agents?
A synced drive as a backup is more than enough.
Sharing a second brain with your partners, or have several sources — you plus your agents — writing to the same files?
That's where Git stops being a developer's affectation and becomes the only thing holding it all together.
One more thing in its favour: Git is free. To get started you lean on GitHub or GitLab, whose free tiers are more than enough. And if you've got data you'd rather not hand to an outside provider, Git is open source: spin up a self-hosted server (Gitea or GitLab CE) on your own VPS and keep everything in-house. Same tool, total control.

.md files (Markdown): documenting effortlessly

Markdown (the .md files) is a way to write formatted text — headings, lists, bold, links — with a handful of simple marks, no Word and no menus. A # makes a heading, a dash makes a list item, two asterisks make something bold.

It's lightweight, readable as it is, and works everywhere. It's the standard for documenting projects and keeping structured notes — and, not coincidentally, the format you'll often use to talk to AI. The four basic rules take ten minutes to learn.

There's one more reason, and it's about AI specifically: Markdown goes down far easier than a PDF. A PDF was built for printing and is stuffed with layout data the model doesn't need and that clutters its context; Markdown is just clean text. For the same content it takes up less of the window and leaves the model with a clearer head.

And the best part: let the AI generate and tidy your .md files — tell it to keep them tight — and it's the AI that adds the links between notes (the wikilinks), the indexes, the cross-references. It quietly builds you a small, navigable second brain, with no formatting on your end.

"But I've got a mountain of PDFs — now what?"

It depends on the use:

Day-to-day PDFs the AI has to reread constantly (manuals, spec sheets, reference docs): convert them to Markdown once and keep those as your working copies. They load into the context clean and light.
Archive PDFs where you only care about the aggregate figure (statements, invoices, receipts): no sense feeding them in one at a time. At the end of the month, pull the numbers you need into a CSV or a spreadsheet and work from that. One clean table beats a hundred PDFs leafed through one by one.
One last tip: to read and manage your .md files painlessly there's Obsidian, a free app made for exactly this. It shows them nicely formatted, follows the links between notes with a click, and turns a folder of .md files into a genuinely browsable archive.

APIs and OAuth: connecting your tools

An API is how two pieces of software exchange information: one program sends a request in a set format, the other replies, automatically and the same way every time. The rules of the exchange — which requests are allowed and what shape the reply takes — are set by whoever provides the API. You don't do whatever you like; you use the operations on offer, in the way intended.

Why do they matter so much?

Because these days APIs are the main connector between all your tools, yours and everyone else's. Almost every serious service — Gmail, Asana, Trello, your business software, even your bank — exposes an API: it's the door your automations come through, and the way one tool talks to another. It's also how an AI works inside your tools instead of staying boxed in its own chat.

But to knock on that door you have to identify yourself, and there are two ways worth telling apart:

API key: a secret code you generate in the service's settings that says "it's me." You use it for your own automations, where you control both ends. It has to be kept safe — more on that later, in the .env section.
OAuth: the "permission handshake." Instead of pasting a key, you click Connect, log in, and grant the app access — without ever handing over your password. It's exactly what happens when you connect Asana or Trello to Claude: a screen asks for permission, you give it, and from then on the two tools talk. You can revoke that access anytime, and the password never changes hands. A distinction that costs real money: subscription or pay-as-you-go API?

Using Claude or ChatGPT through their apps, on a fixed monthly subscription, is the easy path for everyday work: you pay a set fee and get a ready-made interface.

Through an API — via Anthropic's Console or OpenAI's Platform — it works differently: no flat fee, you pay per use, by the token (remember input and output?). It's the route to baking AI into your own tools or automations: more flexible and powerful, but keep an eye on the meter — with top-tier models the figures climb fast, and watching the bill is on you.

To get your bearings:

Use Claude every day and want to connect Gmail, Asana, Drive, Calendar to it?
Subscription + OAuth. Pay the flat fee and link your tools with a click, no keys to handle.
Building agents — cloud or local — that run on OpenAI or Anthropic models?
Generate an API key and add it to the project: that gets you every model the provider offers, often a wider lineup than what's bundled into the monthly plan.
And one handy tool to finish: Postman lets you try out an API before you've written a single line of a real program. You fill in the request in a visual interface, hit send, see the reply. It's the perfect place to learn how a service behaves before you commit to integrating it — without any fear of breaking something.

Python & Co: when you want to build something of your own

An honest heads-up: we're edging into "advanced" territory here, so I'll keep it short.

Want to go further and build yourself some little software of your own?

Don't get stuck on "which language do I pick? how do I develop it?" It depends on what you're making, but a handful of popular, well-documented tools will already take you a long way.

First, two terms you'll hear constantly:

Stack: the set of tools you build software with — the language, the database, the interface. "Picking a stack" means deciding which building blocks you'll put your application together with.
Frontend and backend: the frontend is what the user sees and touches — screens, buttons, forms. The backend is the engine behind the curtain — the logic and the data, which the user never sees. Like a restaurant: the dining room is the frontend, the kitchen is the backend. A solid, widely used starter stack: Python or Node.js (JavaScript) for the logic, PostgreSQL for the database, and a JavaScript framework like React or Next.js for the frontend. Hugely popular tools, packed with guides and examples, and well understood by the AI that'll help you write the code.

A quick word on the languages you'll bump into most.

Python is the go-to for data and AI: it reads almost like English, has a library for nearly everything, and sits right at the crossroads of automation and artificial intelligence. The day you want an AI to crunch data systematically, you'll almost certainly do it here.

Node.js is JavaScript outside the browser: the same language web pages are built with, but running on your computer or a server. It's the natural pick for web apps and anything that lives online. The bonus: learn JavaScript once and you use it for both the frontend and the backend.

Bash is the language of the terminal, the command line: moving files, chaining programs, automating routine tasks. And it's having a moment again for a specific reason: it's how an agent on your machine talks to the computer. When a local agent creates a file, opens a folder, or runs a command, it's using Bash underneath. Knowing the basics is worth it if only to understand what it's doing on your behalf.

Environment variables and .env files: keeping secrets safe

When a program calls an AI through an API, it has to identify itself with a secret key. That key is like your card's PIN — whoever has it spends in your name.

The golden rule: never put keys or passwords in your code. Keep them separate, in environment variables — values that live outside the program — usually in a .env file. The program reads them from there, and that file stays private: never shared, never published.

It's a safe: the important values go inside, not painted on the wall. It's one of the first security habits to pick up, and one of the most ignored by beginners — a stolen key means real charges on your account.

Here's how concrete this gets. With AI, lots of people have thrown themselves into programming without mastering the basics, and they end up publishing their own API keys on GitHub, sometimes in public repositories. The trouble is there are already people combing through those repositories on purpose, hunting for keys to exploit for free — at the unlucky victim's expense.

A bit of documentation: the gift you give yourself

Last, the most underrated habit of all: jotting down a couple of lines about what something does and why. A notes file, a quick line on the reason for a choice.

You don't need a manual. You just need enough that you-in-six-months — who'll have forgotten all of it — can pick it back up in five minutes instead of a whole afternoon. Documentation is a letter to your future self, and your future self will thank you every single time.

Two practical ways to not leave it to chance:

If you use Git, lean on issues: cards built into the repository where you track to-dos, bugs, and ideas you don't want to lose. They stay tied to the project and its history, so your to-do list lives right next to the work instead of scattered across ten places.
If you don't use Git, ask your local agent to keep the documentation in order: index files that act as a map, session files that log what you did and when. Set it up once, and it takes care of it.

The complete picture

On one side you've understood how an AI thinks: the tokens it uses to measure — and bill — everything, input and output alike; the cost that swings wildly between a lightweight model and a top-tier one; the context to keep clean like a desk, compact often and never fill to the brim; the difference between language and multimodal; and prompts — with the system, user and assistant roles — as the main lever for better results.

On the other you've got the workbench: Git so nothing's ever lost (when you actually need it), Markdown to document and talk to AI better, APIs with a key or OAuth to connect your tools, the choice between subscription and pay-as-you-go, Python, Node and Bash to build yourself something of your own, the .env files for secrets, and a bit of documentation for tomorrow's you.

None of this needs a PhD. You just need to see it laid out clearly once — and from there it becomes the common language you use to take AI in hand and put it to work on purpose.

About the Author

I'm Fabrizio from Arkad Consulting.

I help businesses automate workflows using AI agents,
n8n, RAG systems and local AI infrastructure.

Website:
https://arkad-consulting.com

More articles:
https://arkad-consulting.com/en/blog/

Your WordPress Site Is Costing You More Than You Think

Fabrizio — Mon, 04 May 2026 12:01:11 +0000

Why rebuilding from scratch is now faster, cheaper, and smarter than maintaining a legacy content management system

There's a conversation we keep having with clients. It goes something like this:

"We know our site is slow. We know the plugins are a mess. But we've invested so much in WordPress — can't we just... fix it?"

The honest answer? In 2026, fixing WordPress is often more expensive than replacing it. And the reason isn't WordPress itself — it's that the entire paradigm has shifted.

The WordPress Problem Nobody Talks About

WordPress powers roughly 40% of the web. It's an incredible achievement. But here's what happens in practice with most business sites we audit:

The site runs on 15–30 plugins. Each one adds weight, security surface, and maintenance overhead. Some conflict with each other. Some haven't been updated in two years. The theme was customized by a developer who's no longer available, and nobody wants to touch the code because "last time we updated, the site broke."

Meanwhile, every page load triggers a database query, processes a PHP template, assembles the response, and sends it to the visitor. Every single time. Even though the page hasn't changed in three weeks.

It works. But it's slow by design. And the real cost isn't the hosting bill — it's the time your team spends managing a system that fights them at every turn.

The Shift: From Dynamic to Static

Here's what's changed. Five years ago, if you wanted a fast, modern website, you needed a development team and a complex workflow. Today, tools like Astro, Next.js, etc. let you pre-render your entire site into plain HTML files — no server, no database, no PHP. Just static pages served instantly from edge servers around the world.

"But wait — if it's static, how do I update my content?"

This is the question everyone asks. And it's the right one.

The answer is a headless content management system — a content management system that's completely separate from your website's design. You edit your text and images in a clean, modern interface. When you hit publish, the site automatically rebuilds and deploys. Within minutes, your changes are live.

No plugins to update. No theme conflicts. No database to back up. No security patches to worry about.

Sanity: The Content Manager That Gets Out of Your Way

We've been working with Sanity as our headless content platform of choice, and here's why it fits this model so well.

Sanity is a structured content platform. Instead of the classic WordPress editor where you're mixing content with layout (drag this block here, change this column width there), Sanity focuses purely on your content: text, images, data fields. The presentation is handled entirely by the frontend.

This sounds limiting, but it's actually liberating. Because here's a truth about how most clients actually use their content manager:

They change text and images. That's it.

In years of working with small and medium businesses, we've seen the same pattern. The client asks for full control over their site. They get WordPress with a page builder. And then 95% of their edits are: update a price, swap a photo, change a phone number, fix a typo.

Sanity gives you exactly that — a clean, focused interface for the content you actually change. No risk of accidentally breaking the layout. No "the page looks different since I moved that widget."

What about open-source alternatives? Tools like Strapi and Directus offer similar headless content manager capabilities and are fully self-hosted. We haven't battle-tested them on client projects yet, but they're serious options if you prefer to own the entire stack. The core principle is the same: decouple your content from your presentation.

How the Pieces Fit Together

The workflow is straightforward:

Your site is built with a static site generator (we use Astro). All pages are pre-rendered as HTML and deployed to a global content delivery network — in our case, Cloudflare Pages, which serves from 300+ locations worldwide.

Your content lives in Sanity Studio, where your team can edit freely. When they publish a change, a webhook triggers an automatic rebuild. New version deployed. Done.

If your business has external data — a product feed, an API, a booking system — a small scheduled script (a Cloudflare Worker, a cron job, anything) can sync that data daily and trigger the same rebuild process.

But the Real Revolution Is What Comes Next

Here's where it gets interesting.

The static-first architecture isn't just faster and cheaper. It's AI-ready.

When your site is a collection of structured content + a code template, something powerful becomes possible: an AI agent can modify the site directly. Change the copy. Adjust the layout. Add a section. Deploy. All from a simple instruction.

This isn't theoretical. We've built an internal tool called Dedalo — our autonomous development agent — and we're already using it on our own site. A prompt, a review, a deploy. That's the workflow.

Now imagine that for clients. "Add a testimonials section to the homepage" — and it's done. "Translate the site to Spanish" — deployed by morning. "Update the pricing page to reflect our new packages" — live in minutes.

This is the direction we're heading, and we'll be sharing much more about Dedalo and this vision in upcoming articles. But the foundation is the same: a clean architecture where content and code are separate, structured, and accessible to both humans and AI.

What This Means for Your Business

If you're running a WordPress site that's becoming painful to maintain, here's the key insight:

The cost of rebuilding has dropped dramatically. The cost of maintaining legacy systems hasn't.

A modern static site with a headless content manager can be built in two weeks. It'll load faster, rank better, cost less to host, require zero plugin maintenance, and position you for a future where AI handles the routine changes your team currently spends hours on.

WordPress was the right answer for a long time. For many businesses, it's time for the next chapter.

About the Author

I'm Fabrizio from Arkad Consulting.

I help businesses automate workflows using AI agents,
n8n, RAG systems and local AI infrastructure.

Website:
https://arkad-consulting.com

More articles:
https://arkad-consulting.com/en/blog/