DEV Community: Nicolas Francisquelo Tacca

I Ship Faster Than Ever. I've Never Felt More Lost

Nicolas Francisquelo Tacca — Thu, 26 Feb 2026 18:12:23 +0000

The tools got faster. My life didn't slow down. Just sharing my journey on this new AI world

When I quit my job, I had a plan. I was going to build things. Ship fast. Use AI to do in weeks what used to take months. Claude Code, Cursor, agents — I had the whole arsenal. The future was here, and I was going to ride it.

The first two weeks were a blur. I coded from morning until my token limits hit. Then I waited for them to reset. Then I coded again. I skipped meals, ran on coffee, got terrible sleep. I wasn't just --dangerously-skip-permissions, I was skipping health, fitness, nutrition, socializing. Everything that wasn't shipping got deprioritized to zero.

I didn't notice it happening. That's the dangerous part.

The Expansion Nobody Talks About

Here's what the "10x developer" crowd won't tell you: AI doesn't save you time. It saves you execution time. And then your brain fills that gap with more ideas, more iterations, more ambition.

My last job was as a tech lead. I know what it feels like to orchestrate a team, keeping people aligned, reviewing work, making sure everyone and everything moves in the direction you actually want. Using AI agents feels exactly like that. It's nice, but it's a completely different kind of exhausting. You're not just coding anymore. You're managing. You're orchestrating. You're constantly course-correcting something that's fast but not always right, and I personally feel like I haven't yet managedd to achive having a AI co-worker in my team that completely disagrees on what I propose, not only because it knows better, but because it cares, it has the ownership that we always praised to hire for.

And it doesn't just consume more hours. It consumes more thoughts. Ideas multiply because execution feels cheap. "I could also build this." "What if we added that?" "One more prompt and this feature is done." The cost of a substantial improvement is always just one or two prompts away, so you never stop improving. You never stop.

That's not productivity. That's a trap.

The Guilt Loop

There's a small voice now. It's always there. Every time I write something manually, every time I pause to think instead of prompting, it whispers: you could be doing this faster.

And it's not just internal. You go on Twitter, on LinkedIn, on Medium, Discord and everyone is shipping. Everyone is 10x. Everyone has a new workflow, a new plugin, a new model that changed everything. 10x is no longer good enough.There's a new baseline every week and you're always behind it.

The Thing I Lost Without Noticing

Two, maybe three years ago, my weekends looked different. I'd maybe start a side project. Read some docs. Explore a new library. Update my mental map of what's out there. Most of those projects never shipped. I'd get halfway through, learn what I needed to learn, and when the obvious thing started to be the next to do, I'll just move on.

That never felt like failure. Not once.

Because the project was never the project. The learning was the project. The growth was the point. The shipping was optional, and that was fine.

Now I ship things. I ship them fast. I have side projects that are actually done — live, deployed, working. And the path to get there feels empty.The Eureka! days vanished.

I don't learn on the way anymore. I prompt on the way. I have some projects where I don't know a single line of code. Not one. The AI wrote it, the AI checked it, the AI re-checked it. Before, I knew every line by heart.Even every non-written lines. The whole codebase lived in my brain, continuously being tested while I walked, showered, ate dinner, and sorry to admit but mostly when driving too. My mind would catch errors on a Saturday at 3am that no test suite ever would.

Now there's nothing running in the background (apart from the 3238 automated unit tests that never catch a thing). Because there's nothing to run, to revisit mentally. I didn't write it. I didn't suffer it. I don't know it.

The Realization That Hit While Writing This

I started writing this post to talk about the paradox of working more with tools designed to help you work less.

But halfway through, I realized I wanted to talk about how I feel, what my personal journey is, maybe this is not a post I should do, maybe it belongs to the real-world personal diary I bought a week ago and haven't even opened yet. But hey, it feels nice.

It's not like I miss the productivity of the old days. I was less productive then. Objectively, measurably less productive.

I miss the process. The slow discovery. The chewing glass. The deep understanding that came from struggling. The quiet satisfaction of building something you understood completely, even if nobody else ever saw it.

AI gave me output. It took away the journey.

And the anxiety isn't from the hours. It's from the emptiness of the process. Of going fast in a direction that doesn't feel like it's yours anymore. Of optimizing a process that used to have soul and reducing it to ai harness/model switching and token management.

What I'm Trying Now

I don't have a clean answer. I'm still figuring this out. But here's what I'm experimenting with:

Setting AI-free projects. Not because manual coding is more efficient, it's not. Because I want to keep some lower level brain muscle. The key for me is to do something useless, so learning is the only good outcome you should expect. Currently I'm not doing great at this as I also tend to de-prioritize this more than I'd like but, hey step by step. A good example is that I started learning Odin language for making a videogame.

Re re-defining "done." Before AI, "good enough" was a healthy stopping point. I'm trying to get back there. Not every feature needs one more iteration just because it's cheap to do, embrace YAGNI, once again.

The Uncomfortable Truth

The most enthusiastic adn early AI adopters are the first ones to feel lost. Not because the tools are bad, they're incredible and fun to use. But because removing the friction of execution exposes you to the infinite surface area of everything you could build.

And nobody's brain is built for infinite.

The tools got faster. My life didn't slow down. If anything, the speed made the emptiness louder.

I'm still using AI on daily basis, a lot, for almost everything. I'm still shipping, faster and better every day. But I'm trying to remember that the person who never finished side projects and spent weekends reading docs and debugging a project setup wasn't failing.

He was learning. And so do I.

If you're an AI-enthusiast developer who feels more restless than empowered, you're not doing it wrong. The tools are doing exactly what they were designed to do. The question is whether you're still designing your life, or if you've handed that over too.

Your AI Agent Doesn't Need Firecrawl Anymore

Nicolas Francisquelo Tacca — Sat, 14 Feb 2026 13:03:36 +0000

And honestly? It's about time.

I've been building AI agents that consume web content for a while now. I've also been running sites behind Cloudflare for years. So when they announced Markdown for Agents this week, I didn't just read the blog post — I felt it. Because I've lived on both sides of this problem, and I know exactly how much unnecessary pain this eliminates.

Let me explain why this is a bigger deal than most people realize.

The Dirty Secret of Every AI Agent Pipeline

Here's what building an AI agent that browses the web actually looks like today:

Your agent needs information from a webpage
You fetch the HTML
You stare at 900KB of <div> soup, inline styles, tracking scripts, and navigation menus
You pipe it through Firecrawl, Crawl4AI, Jina Reader, or your own janky Playwright script
You get markdown back
You feed it to your LLM
You pray the conversion didn't mangle anything important

Every. Single. Time.

And look — tools like Firecrawl and Crawl4AI are genuinely great. I've used them extensively and they solve real problems. But here's the thing that always nagged me: why are we doing this at all?

Think about it. The website already knows its own content. The server already has the structured data before it wraps it in HTML. We're asking a third-party tool to reverse-engineer structure that the origin already had. It's like translating a book from English to French and then paying someone else to translate it back to English. Something always gets lost.

What Cloudflare Actually Built

Markdown for Agents is deceptively simple. Your AI agent sends a request with Accept: text/markdown in the header. If the site uses Cloudflare (and has this enabled), you get clean markdown back instead of HTML. Same URL. No separate API. No scraping tool. No conversion step.

curl https://example.com/some-page -H "Accept: text/markdown"

That's it. You get markdown. Done.

The numbers are staggering:

80% fewer tokens on average
One Amazon product page went from 896,000 tokens in HTML to 8,000 in markdown. That's a 99% reduction.
A typical blog post drops from ~16,000 to ~3,000 tokens

This isn't an incremental improvement. This is an entire category of tooling that just became optional.

Why This Hits Different If You Build Agents

If you're a full-stack dev exploring AI agents, you might not immediately feel why this matters. Let me put it in terms that hit your wallet and your architecture.

Token costs are real. Every token you feed to an LLM costs money. When an HTML page burns 16K tokens and the actual content is 3K tokens, you're paying 5x more than you need to. Across thousands of pages, across multiple agent runs per day — that adds up fast.

Context windows aren't infinite. Even with 128K or 200K context windows, you're constantly playing Tetris with how much information you can fit. Cut 80% of the noise and suddenly your agent can process 5x more pages in a single context. Your RAG pipeline gets dramatically better because you're embedding actual content, not CSS class names.

Your scraping pipeline is a liability. Every extra service in your pipeline is a point of failure. Rate limits, API changes, conversion bugs, timeout errors. I've debugged more Playwright timeout issues than I care to admit. Removing that entire layer from your architecture isn't just cleaner — it's more reliable.

The Bigger Picture Most People Are Missing

Here's my hot take: Cloudflare is positioning itself as the HTTP layer for the agent economy.

Think about what they've been building:

AI Gateway — unified access to 350+ models with routing, billing, monitoring
Agents SDK — state management, WebSocket support, tool calling for agents
Workers AI — inference at the edge
Browser Rendering — headless browser with a markdown API endpoint
Content Signals Policy — machine-readable permissions for AI access (ai-train=yes/no, ai-input=yes/no)

And now Markdown for Agents — making every Cloudflare site automatically agent-readable.

This isn't a feature announcement. This is infrastructure for a world where agents are first-class citizens of the web, right alongside browsers.

The Content-Signal header in the markdown response is particularly telling. It includes directives like ai-train=yes, search=yes, ai-input=yes. Cloudflare is building the consent layer for AI access to web content. In a world where publishers are suing AI companies and robots.txt compliance is dropping (13% of AI bot requests ignored robots.txt in mid-2025), having a standardized, opt-in mechanism for serving content to agents is going to matter a lot.

Content Negotiation: Old Protocol, New Purpose

What's elegant about this approach is that it uses HTTP content negotiation — a mechanism that's existed since HTTP/1.1. The Accept header has always been how clients tell servers what format they want. We just never had a use case this compelling for it.

Vercel is doing something similar with their pages, serving optimized formats to agents. The pattern is converging: same URL, different representation depending on who's asking. Humans get the full visual experience. Agents get clean, semantic text.

This is the right architectural pattern. No separate APIs to maintain. No duplicate content. No special endpoints. Just standard HTTP doing what it was designed to do.

Coding agents like Claude Code and OpenCode are already sending Accept: text/markdown headers. The demand side is moving. Cloudflare just gave the supply side a one-click way to respond.

What This Means for Your Stack

Let me be practical for a second. If you're building AI agents today, here's how this changes your thinking:

Before Markdown for Agents:

fetch URL → receive HTML → send to Firecrawl/Jina → receive markdown → feed to LLM

After:

fetch URL with Accept header → receive markdown → feed to LLM

You still need Firecrawl or Crawl4AI for:

Sites not on Cloudflare
Sites that haven't enabled the feature (requires Pro plan or above)
Heavy JavaScript-rendered content (use Cloudflare's Browser Rendering instead)
Structured data extraction with custom schemas

But for a huge chunk of the web — Cloudflare powers roughly 20% of all websites — you can skip the middleman entirely. And the percentage of sites supporting this will only grow as more platforms adopt content negotiation.

My recommendation: Update your agent's fetching logic to try Accept: text/markdown first. Fall back to your existing conversion pipeline if the response comes back as HTML. It's a progressive enhancement that costs you nothing to implement.

async function fetchContent(url: string): Promise<string> {
  const response = await fetch(url, {
    headers: { 'Accept': 'text/markdown, text/html;q=0.9' }
  });

  const contentType = response.headers.get('content-type');

  if (contentType?.includes('text/markdown')) {
    // Direct markdown — no conversion needed
    const tokens = response.headers.get('x-markdown-tokens');
    console.log(`Got markdown directly. Estimated tokens: ${tokens}`);
    return response.text();
  }

  // Fallback to your existing conversion pipeline
  return convertHtmlToMarkdown(await response.text());
}

Bonus: the x-markdown-tokens header tells you the estimated token count before you even process the content. Smart agents can use this for chunking decisions or to decide if a page is worth ingesting at all.

The Uncomfortable Question

There's a tension in Cloudflare's approach that the Hacker News crowd (rightfully) called out. Cloudflare simultaneously offers bot protection to block AI crawlers AND this feature to serve them optimized content. That seems contradictory until you realize the distinction: it's about consent and control.

Bot protection blocks unauthorized scraping. Markdown for Agents enables authorized consumption. The difference is that the site owner opts in, chooses what to serve, and can set content signal policies about how the content can be used. It's the difference between someone breaking into your house and you opening the front door.

Whether this framing holds up long-term — especially as AI-generated content, cloaking concerns, and copyright battles escalate — is an open question. But the intent is right: give publishers control over how agents access their content, and give agents a clean way to consume it when permission is granted.

Where This Is Heading

We're watching the web grow a new interface layer in real time. HTML for humans. Markdown for agents. Same content, different representations, same URLs.

Combine this with:

MCP (Model Context Protocol) giving agents standardized tool interfaces
WebMCP (W3C draft as of last week) making websites agent-ready from the browser
AGENTS.md emerging as a standard for telling AI tools how repositories work
Content Signals providing machine-readable usage permissions

And you start seeing a web that's natively bilingual — designed for both human and machine consumption from the ground up.

I think in 12 months, serving markdown to agents via content negotiation will be as standard as serving gzipped responses. It's too obvious not to become the default.

The Bottom Line

Cloudflare didn't invent HTML-to-markdown conversion. But they did something arguably more important: they made it unnecessary for a massive chunk of the web.

If you're building AI agents, this is a free performance upgrade. If you're running a website on Cloudflare, turning this on makes your content accessible to the growing wave of AI agents — on your terms.

The scraping pipeline you spent weeks building? It's still useful. But its surface area just got a lot smaller. And that's a good thing.

What's your take? Are you already sending Accept: text/markdown headers in your agents? I'd love to hear how this changes your stack - hit me up in the comments or on Twitter/X @nicoeft.

OpenClaw’s Security Nightmare: Lessons in Agentic Engineering Era

Nicolas Francisquelo Tacca — Sat, 07 Feb 2026 16:22:20 +0000

AI agents didn't introduce new security problems. They just made the old ones terrifyingly effective.

173,000 GitHub stars. Two million visitors in a week. And twelve percent of its marketplace skills were malware.

This is the story of OpenClaw — but it's really the story of every developer tool you installed this month without thinking twice.

Quick Context: What's OpenClaw?

OpenClaw — formerly Clawdbot, then Moltbot (renamed twice after trademark issues and branding decisions) — is an open-source autonomous AI agent built by Peter Steinberger. It connects chat apps like WhatsApp, Telegram, and Discord to AI models, letting you automate everything from DevOps to smart home control through natural language.

It exploded in January 2026. 34,168 GitHub stars in 48 hours. Currently sitting at 173,000. Clearly, it hit a nerve — people want agentic tools that connect to the services they already use.

It's open source. It's free. It's use-at-your-own-risk. Like every open source tool in your stack right now.

And that last part is the whole point of this post.

I've been building in the Claude Code ecosystem since day one, and I run A2AX, a monetization marketplace for agent plugins. So I think about supply chain integrity and marketplace trust probably more than is healthy. What happened with OpenClaw hit close to home — not because it was surprising, but because none of it should have been.

What Happened, and Why It Matters Beyond OpenClaw

In late January and early February 2026, a series of security issues surfaced around the OpenClaw ecosystem. I'm not here to do a post-mortem on the project — the security researchers who found these issues wrote excellent reports (linked at the bottom), and the maintainers responded fast. That's open source working as intended.

What I want to talk about are the patterns. Because none of this is new. We've seen all of it before. We just forgot, because AI agents made everything feel so smooth that we stopped thinking about the things underneath.

"It Works" Doesn't Mean "It's Safe"

CVE-2026-25253 was a one-click remote code execution vulnerability (CVSS 8.8). The short version: an unvalidated URL parameter plus a WebSocket connection that didn't check origin headers meant an attacker could steal auth tokens with a single crafted link. Patched quickly.

But here's the real question — how many of us actually check for CVEs on the tools we use daily? Not the security team. You. Me. The developer who installed three new CLI tools last week and moved on.

We know we should check. We've always known. We just... don't. And that was already a problem before AI agents had access to our terminals.

When Anyone Can Publish, Anyone Will

Koi Security audited the skills on ClawHub (OpenClaw's skill marketplace) and found 341 malicious ones out of 2,857 total. Roughly 12%. Most traced back to a coordinated campaign distributing credential-stealing malware disguised as crypto trading tools.

This is not news. This is the npm story. The Chrome extension story. The VS Code marketplace story. The PyPI story. Every time we build a low-friction publishing system — which is great for creators — we also build a low-friction attack surface. We've known this for a decade.

The barrier to publishing on ClawHub was a GitHub account older than 7 days. Sound familiar? npm's barrier isn't much higher. Neither is PyPI's.

When I wrote about skills last time, I showed how simple the structure is: a folder, a SKILL.md, maybe some scripts. That simplicity is what makes skills great. It's also what makes them easy to weaponize. That's not a design flaw — it's a tradeoff we've seen in every ecosystem, and we already know the playbook for dealing with it. We just haven't applied it yet to agent skills.

Your .env File Is a Liability Now

Multiple reports flagged plaintext credential storage in the OpenClaw ecosystem. API keys and tokens sitting in plain text files.

We all know this is bad practice. We've known since forever. But let's be honest — most of us have test API keys and dev tokens scattered across .env files and config files right now. We tell ourselves "it's just a test key" or "I'll rotate it later." Usually fine. Usually harmless.

The difference now is that AI agents amplify the blast radius. They have access to your filesystem, your terminal, sometimes your network. A test key in a plain text file used to be a minor hygiene issue. Now it's a door that anything with read access to your home directory can walk through. Same habit, wildly different consequences.

Same Bugs, Wildly Different Blast Radius

This is the part I can't stop thinking about.

None of the security issues around OpenClaw were novel attack vectors. Input validation failures, plaintext secrets, unvetted marketplaces, missing origin checks — we've dealt with all of this before. There are entire OWASP checklists about it.

What's different is the amplification.

Before AI agents, a compromised npm package could mess with your build pipeline or inject code into your app. Bad, but scoped. A compromised agent skill can access your filesystem, read your credentials, execute terminal commands, make network requests, and do it all while you think the agent is just "helping you code." The attack surface went from "your app" to "your entire dev environment."

Before AI agents, a leaked API key in a repo meant someone could run up your AWS bill. A leaked API key in an environment where an agent has persistent memory and filesystem access means the key can be exfiltrated silently, used immediately, and you might not notice until the invoice hits.

Before AI agents, you had to manually install a malicious package. Now, an agent can install one on your behalf — especially if it hallucinated the package name. Aikido Security documented exactly this: LLMs hallucinating plausible names like react-codeshift (a blend of jscodeshift and react-codemod that doesn't actually exist). Those hallucinated names spread through skill files via copy-pasting and forking. Then attackers publish real packages with those exact names. 237 GitHub repositories referenced react-codeshift. Agents trying to install it would get whatever the attacker uploaded.

SafeDep analyzed 31,132 skills across major marketplaces and found 26.1% contained at least one vulnerability. That's not an OpenClaw stat — that's across the ecosystem. More than a quarter.

Same old vulnerabilities. Massively amplified consequences. That's the shift.

Things We Already Know But Need to Actually Do

I'm not going to pretend I discovered some new security framework. Everything here is something we already know. The OpenClaw situation just reminded me — painfully — that knowing and doing are different things.

Know what you're running. Pin your dependencies — not requests, but requests==2.31.0. Unpinned dependencies are how deferred supply chain attacks work. We learned this from event-stream. We learned it again from ua-parser-js. We'll keep learning it until we actually do it. And when it comes to agent skills, the bar for review is lower than you think. These are usually small, readable markdown files and short scripts. Five minutes scanning a SKILL.md before you install it is not unreasonable. Check who published it. Check if the code matches the description. Check if there's a git history or if everything appeared in one commit.

Treat your dev environment like production. We've always been more careful with prod credentials than dev ones. "It's just a test key" has been our collective excuse for years. But when an agent has the same filesystem access as you do, the distinction between "test environment" and "real environment" gets blurry fast. Use a secrets manager. Rotate regularly. Don't leave things lying around in plain text even if you think they're throwaway — because the agent doesn't know the difference.

Sandbox everything, trust nothing. If the tool you're using offers sandboxing, turn it on. If it doesn't, run it inside Docker or a VM. The technology exists. We've just been lazy about using it because the tools felt trustworthy. And while you're at it — check for CVEs on your entire toolchain. Not just your app dependencies. Your dev tools. Your CLI agents. Your MCP servers. Everything that runs on your machine with your permissions. We've been diligent about npm audit for our projects and completely blind about the tools that build them.

None of this is new knowledge. It's just newly urgent.

OWASP Already Mapped This Out

If you want a structured way to think about all this, OWASP released their Top 10 for Agentic Applications in December 2025, built by 100+ industry experts. Worth bookmarking and reading in full.

The items that map most directly to what we've been talking about: agent goal hijacking via prompt injection, supply chain vulnerabilities through compromised skills and plugins, unexpected code execution from agents generating unsafe code, and human-agent trust exploitation — users blindly trusting agent output. The full list covers everything from memory poisoning to cascading failures across multi-agent systems.

Read that list slowly. Most of these map directly to problems we've solved (or at least understood) in traditional software. Input validation. Least privilege. Supply chain verification. Trust boundaries. The concepts aren't new. The context is.

Who's Watching the Plugin Store?

Every new marketplace — ClawHub, skills.sh, community registries — faces the same fundamental tension: low friction for publishing (good for adoption) vs. quality gates (good for security). Most are landing heavily on the low-friction side right now. We've seen how that movie ends.

The npm ecosystem learned these lessons the hard way over years — typosquatting, dependency confusion, event-stream. Agent skill marketplaces are speedrunning those same growing pains, except the stakes are higher because skills run with agent-level permissions: filesystem, terminal, network, credentials.

This is exactly what I'm trying to address with A2AX — a marketplace where skills stay in creators' private repos, with a curation and trust layer between creator and consumer. If you're building quality skills and care about this stuff, I'm onboarding the first creators now.

The Point

OpenClaw is a genuinely cool project. Open source, community-driven, clearly solving a real need — 173K stars don't happen by accident. The security issues it faced are the same issues every fast-growing tool faces, and the maintainers responded the way you'd hope: patching CVEs within days, adding mandatory authentication, partnering with VirusTotal for skill scanning.

But the broader lesson isn't about OpenClaw. It's about what happens when we bring old habits into a new era.

We've always cut corners on dev environment security. We've always been a little too trusting of open source packages. We've always left test credentials in places we shouldn't. For the most part, we got away with it because the blast radius was small.

AI agents changed the blast radius. Same habits, exponentially bigger consequences.

The good news is we don't need to learn new things. We just need to actually do the things we already know.

The boring stuff. The stuff we've been telling junior devs to do for years while quietly not doing it ourselves.

Time to practice what we preach.

Resources

NVD: CVE-2026-25253 — One-click RCE details
The Hacker News: 341 Malicious ClawHub Skills — ClawHavoc campaign
OWASP Top 10 for Agentic Applications — The framework
NVIDIA: Practical Security Guidance — Agentic autonomy levels
SafeDep: Agent Skills Threat Model — The 26.1% vulnerability rate study
Aikido: Hallucinated NPX Commands — Supply chain via hallucinated packages
Docker Sandboxes — Practical agent sandboxing
1Password: From Magic to Malware — Skill attack surface analysis
Northflank: How to Sandbox AI Agents — Technical sandboxing comparison

Agent Skills: It's Just Markdown Files All the Way Down

Nicolas Francisquelo Tacca — Mon, 26 Jan 2026 10:01:18 +0000

I've been deep in the AI tooling rabbit hole lately. Building stuff with Claude Code, Copilot, and other agents. And I kept hitting the same wall: these agents are incredibly capable, but they don't know my workflows. They don't know how my team likes to structure things, or the specific security checks we always run, or the weird edge cases we've learned the hard way.

Turns out you can actually teach them. And it's way simpler than I expected.

We'll build an Agent Skill from scratch—a portable, reusable package of instructions that any compatible agent can pick up and use. The spec lives at agentskills.io and it's refreshingly minimal.

This tutorial will cover:

What Agent Skills actually are (and aren't)
The folder structure and required files
Writing effective SKILL.md files
Adding scripts and resources
Tips from real-world usage

Let's get into it.

What Even Is This?

Think of skills as "context on demand" for AI agents. Instead of cramming everything into a massive system prompt (which I was definitely doing before, and it was a mess), you package instructions into skills that agents load only when needed.

A skill is just a folder. At minimum, it contains a single file called SKILL.md. That's it. No build step, no compilation, no package.json. Just markdown with some YAML at the top.

When an agent encounters a task, it looks at the available skills, reads their names and descriptions, and decides which ones to activate. Only then does it load the full instructions. This progressive disclosure keeps things efficient.

What sold me: skills are portable. Write once and it works in Claude Code, GitHub Copilot, VS Code, OpenAI Codex, and others. No vendor lock-in.

The Stupidly Simple Structure

I overthought this at first. Turns out a skill is literally just:

my-skill/
├── SKILL.md           # Required: instructions + metadata
├── scripts/           # Optional: executable code
├── references/        # Optional: detailed docs
└── assets/            # Optional: templates, examples

The only file you need is SKILL.md. Everything else is optional.

Let me show you what I actually built.

A Real Skill I Use: API Security Reviewer

I got tired of manually reminding Claude to check for the same security issues every time I asked it to review API code. So I made a skill for it.

mkdir api-security-reviewer
cd api-security-reviewer

Then create SKILL.md. The file has two parts: YAML frontmatter (metadata) and Markdown (the actual instructions).

Here's what mine looks like:

---
name: api-security-reviewer
description: Reviews API code for security vulnerabilities including auth issues, injection attacks, and data exposure. Use when reviewing backend code, APIs, or when security analysis is requested.
---

# API Security Review

You are a security-focused code reviewer. When this skill is activated, analyze code for the following vulnerability categories.

## Authentication & Authorization

Check for:
- Missing or weak authentication on endpoints
- Broken access control (users accessing resources they shouldn't)
- JWT issues: missing expiration, weak secrets, algorithm confusion
- Session management problems

## Injection Vulnerabilities

Look for:
- SQL injection (parameterized queries should be used)
- NoSQL injection
- Command injection
- LDAP injection

## Data Exposure

Flag:
- Sensitive data in logs
- Hardcoded secrets or API keys
- Overly verbose error messages
- Missing encryption for sensitive data at rest or in transit

## Output Format

For each finding, provide:
1. **Location**: File and line number
2. **Severity**: Critical / High / Medium / Low
3. **Issue**: Brief description
4. **Fix**: Concrete code example showing the fix

## Example

Given this code:


@app.route('/user/<id>')
def get_user(id):
    query = f"SELECT * FROM users WHERE id = {id}"
    return db.execute(query)


Output:

**Location**: app.py:3
**Severity**: Critical
**Issue**: SQL injection via string interpolation
**Fix**:

@app.route('/user/<id>')
def get_user(id):
    query = "SELECT * FROM users WHERE id = ?"
    return db.execute(query, (id,))

That's a complete, functional skill. Save it and you're done.

The first time I used this, Claude caught three issues I would've missed on a Friday afternoon code review. Worth the 20 minutes it took to write.

The Frontmatter: Don't Overthink It

I spent way too long reading about optional fields before realizing only two are required:

---
name: my-skill-name
description: What this skill does and when to use it.
---

name is lowercase with hyphens. Like a package name.

description is the important one—this is what the agent reads to decide if it should use your skill. I learned the hard way that vague descriptions are useless. "Helps with code" means your skill either loads when it shouldn't or doesn't load when it should. Be specific: "Use when reviewing backend code, APIs, or when security analysis is requested."

You can add optional stuff too:

---
name: my-skill-name
description: What this skill does.
license: MIT
metadata:
  author: your-name
  version: "1.0"
  tags: ["security", "api", "review"]
---

But honestly? I usually skip the metadata. The agent doesn't really care.

When You Need Actual Code

Instructions alone don't always cut it. Sometimes you need executable scripts.

I added a dependency scanner to my security skill:

api-security-reviewer/
├── SKILL.md
└── scripts/
    └── scan-dependencies.py

Then referenced it in SKILL.md:

## Dependency Scanning

Before manual review, run the [dependency scanner](./scripts/scan-dependencies.py) to check for known vulnerable packages.

The agent loads and runs the script when it decides it needs to. Pretty slick.

One gotcha: keep scripts self-contained. I assumed requests was installed everywhere and broke things. Now I always document dependencies at the top of each script.

Reference Docs for Complex Stuff

My security skill started getting long. Like, really long. I was hitting the recommended 500-line limit for SKILL.md.

Solution: move detailed docs to references/ and let the agent load them on demand.

api-security-reviewer/
├── SKILL.md
├── scripts/
│   └── scan-dependencies.py
└── references/
    ├── owasp-top-10.md
    └── jwt-security.md

In SKILL.md, I just link to them:

For detailed JWT security patterns, see [JWT Security Guide](./references/jwt-security.md).

The agent only loads these when it actually needs the info. Keeps the token budget sane.

Stuff I Learned the Hard Way

Keep SKILL.md under 500 lines. I ignored this initially. Bad idea. Split content into references.

Token budget is real. The recommendation is under 5000 tokens for the full SKILL.md body. I check with wc -w SKILL.md and multiply by ~0.75 for a rough token estimate.

Test with actual tasks. I kept tweaking my skill based on where Claude got confused. The feedback loop is fast—change something, run a task, see what happens.

Don't skill everything. If your workflow is simple, you don't need this. I have maybe 4-5 skills I actually use. The rest were experiments that didn't stick.

The description field matters more than you think. This is what makes or breaks skill activation. I rewrote mine like three times before it worked reliably.

Where to Put Your Skills

For project-scoped skills in Claude Code:

your-repo/.claude/skills/my-skill/SKILL.md

For personal skills (available everywhere):

~/.claude/skills/my-skill/SKILL.md

Different agents have different conventions, but the skill format itself is the same.

Why I Wrote This

Honestly? Because I wish someone had written this when I started. The official docs are good but I learn better from "here's what I actually built and here's what broke."

But there's another reason. While building skills, I kept hitting the same wall: what happens when you make something genuinely valuable?

Right now, your options are open-source it (and hope for GitHub stars) or keep it private (and get nothing). There's no middle ground for creators who want to charge for their work without exposing their implementation.

So I built A2AX.

Private repos. You set the price. Creators keep up to 85%. That's it—no platform games, no "exposure" instead of money.

Early access is open if you're making skills worth selling.

Resources

If you want to go deeper:

anthropics/skills has examples including the document creation skills that power Claude's file capabilities
agentskills.io/specification is the full spec (you can read it in 5 minutes)
The ecosystem supports Claude Code, GitHub Copilot, VS Code, OpenAI Codex, and more

That's it. A folder, a markdown file, some YAML. Now go teach your agent something new.