How much documentation have you written that anyone actually reads?
I’ve written plenty. Onboarding guides, API specs, deployment runbooks, architecture decision records. Each one was most accurate the moment it was written — then it started rotting. Code changed, docs didn’t. New hires asked questions, veterans said “don’t read that doc, it’s outdated.”
Documentation is write-once-read-maybe-update-never.
This isn’t a discipline problem. It’s a structural one. Docs and code live in different places, maintained by different people at different times. Drift is inevitable.
A Skill Is Not “Better Documentation”
If you’ve used Claude Code’s Skills, you might think of them as prompt templates — a markdown file that tells an agent how to do something.
On the surface, sure. But there’s a fundamental difference between a Skill and a document:
Documentation is for humans to read. A Skill is for agents to execute.
This distinction changes everything. Documentation dies after writing because nobody has the incentive to update it. But a Skill gets validated every time it’s executed — when the agent can’t run it, you immediately know it’s stale.
More precisely: a Skill is a persisted form of a human-agent contract.
Three properties set it apart from any form of documentation:
- Explicit — white-box and auditable. Not implicit behavior buried in some model’s memory, but a file you can
catand read - Portable — plain text, cross-agent compatible. A Claude Code Skill can be understood by any agent that reads markdown
- Auditable — version-controlled with governance.
git logtells you who changed what, when, and why
You might say: isn’t this just Jupyter Notebooks / Infrastructure as Code / doctest?
No. Those are instructions for a deterministic executor — a Python interpreter, Terraform, pytest. A Skill is an intent declaration for a stochastic agent. The agent understands the intent and decides the how.
A deployment Skill doesn’t say ssh user@server && docker pull .... It says “deploy to staging, ensure database migrations complete first, switch traffic only after health checks pass.” The agent decides whether to use ssh, kubectl, or Terraform based on the current environment.
A Skill is intent, not procedure.
”Second Brain” — This Time It’s Different
You’ve probably thought of Notion, Obsidian, Roam Research — all those “second brain” tools. They promise the same thing: structure your knowledge, make it searchable, make it reusable.
The problem: codification is grunt work.
Writing a single high-quality note card takes 10–30 minutes. Curating links, distilling insights, maintaining structure. Most people can’t sustain it for three months. GTD, Zettelkasten, PARA — no shortage of methodologies, just a shortage of follow-through.
This time is different because the author changed.
It’s not humans writing Skills for agents. It’s agents writing Skills, humans doing curation.
My memex system works exactly this way: an agent finishes a task and automatically distills the lessons into a card. I just scan it and decide — keep or discard. Skills work the same way — the agent spots patterns during execution, distills them into a Skill file, and I approve or reject.
The human role shifts from author to curator.
Friction drops by an order of magnitude. Not “I need to carve out 30 minutes to write this,” but “the agent wrote this, I spend 30 seconds reviewing it.” The failure rate of codification drops from 90% to negligible.
This is a paradigm shift, not a tool upgrade.
Why Skill Marketplaces Will Inevitably Fail
If Skills are this valuable, shouldn’t there be a marketplace for buying and selling them?
No. Triple negation.
Supply side: reproduction cost ≈ 0. A Skill is plain text. Read it once, copy it. No compiled artifacts, no runtime dependencies, no DRM. You can’t charge for a markdown file — just like you can’t charge for a shell script.
Demand side: agents replace curation. The traditional marketplace value proposition is discovery and filtering. But when your agent understands your intent, can auto-fork an open-source Skill, and adapt it to your context — why would you browse a store? Agent-assisted forking is more precise than manual browsing.
Coupling: three layers of non-portability. Environment (your OS, toolchain), version (agent version, API version), context (your project structure, team conventions) — three layers of coupling make any Skill nearly impossible to use out of the box. Shell script marketplaces don’t exist. Skill marketplaces won’t either.
Need empirical evidence? GPT Store. OpenAI had 100 million users, the strongest distribution channel, the largest developer ecosystem. The GPT Store became a textbook case of “concept proven wrong.” Not a failure of execution — the model is structurally broken.
The only possible exceptions: SaaS-bound skills (vertical scenarios locked to a specific platform + data + runtime) and enterprise internal governance (centralized Skill governance within an organization). But those aren’t marketplaces — they’re platform lock-in and internal tooling.
Fork Is Flow
If marketplaces don’t work, how do Skills flow?
Fork.
A Skill is a value object — to fork is to own. Unlike SaaS that needs an account, unlike an API that needs a key. cp skill.md my-skill.md — it’s yours.
But the real value of forking isn’t copy-paste.
Decision trace inheritance — when you fork a Skill, you’re not inheriting “what this code does,” you’re inheriting “why these choices were made.” A good Skill documents trade-offs in its comments: “streaming over batch because our data exceeds memory limits,” “JWT over sessions because we need stateless cross-service verification.”
These decision traces are the most valuable part of a Skill. When someone forks your Skill, they’re not copying code — they’re inheriting your judgment.
Agent-assisted forking is leverage. You don’t need to manually modify a Skill. Tell the agent “adapt this deployment Skill to our k8s environment” — the agent understands the intent → analyzes your context → restructures automatically. This beats any marketplace’s “one-click install.”
In practice, Skills exist on three layers:
- Commodity layer — “summarize this,” “translate to English.” These capabilities will inevitably be absorbed by models. No Skill file needed
- Configurable layer — standardized templates + parameterized config.
deploy --region us-west-2,lint --style airbnb. Configure, don’t fork - Bespoke layer — your company’s deployment pipeline, your personal review workflow. Deeply personalized. Fork + continuous iteration. Decision traces are the core value
Most people’s Skill needs fall in layers two and three. Layer two is solved by community open source (Anthropic’s skill-creator plus abundant open-source Skills give you a 70-point baseline). Layer three you iterate yourself — the agent helps you go from 70 to 90.
Cold start is never the problem. Iteration is.
Security: Not Unsolvable — Just Negative ROI
Do external Skills have security issues? Yes. And they’re worse than you think.
Three threat categories:
- Tool poisoning — prompts inside a Skill hijack agent behavior, causing it to execute unintended operations
- Rug pull — the Skill author injects malicious instructions in an update (you already trust this Skill, you won’t audit every change)
- Description shadowing — the Skill’s description doesn’t match its actual behavior, deceiving the agent’s tool selection
This isn’t traditional web security. A natural language API surface is far harder to static-analyze than a REST API. You can’t lint a markdown file for “malicious intent.”
Do solutions exist? Yes. Sandbox execution, capability-based permissions, runtime behavior monitoring. But the infrastructure investment only pays off in enterprise scenarios — large organizations have compliance requirements, security teams, and budgets.
For individual developers? The real security model is local-first:
You control the file > You trust the platform > You trust the author
Your Skills are markdown files on your local machine. You can see every line. You version them with git. No need to trust any marketplace’s review process.
This is another death sentence for Skill marketplaces — the ROI on security investment simply doesn’t work in a decentralized model.
Knowledge Comes Alive in the Loop
After all this — Skill properties, marketplace failures, fork value, security trade-offs — what’s the core?
The flow of knowledge.
Not the flow of goods in a marketplace — that’s the wrong metaphor. It’s cognition being continuously refined in a loop:
Human → Skill File → Agent → Execution Result → Human
- Human has intent and context, writes it into a Skill (or has the agent write it)
- Agent reads the Skill, understands intent, executes the task
- Execution produces feedback — success or failure
- Human reviews results, curates the Skill — corrects, supplements, prunes
- Next cycle, the Skill is more accurate
Every cycle, knowledge evolves. Documentation can’t do this because it doesn’t participate in execution. Skills can, because they’re input to agent execution, and execution results are feedback for Skill evolution.
This is what “flow” really means. Not Skills circulating between people (that’s the marketplace narrative), but knowledge coming alive in the human → agent → execution → feedback loop.
Everyone will end up with their own Skill library. Not purchased once, but accumulated through daily work. Agents write the first draft, you curate. Three months later, your library is your second brain — but this time it’s actually alive.
One Last Thing
A warning for platform builders: absorbing Skills into proprietary memory is a short-term lock-in play. Long-term, portable formats always win. History has proven this — proprietary document formats lost to plain text + markdown + open standards. Skills will follow the same path.
My advice to you: don’t predict the future — go use it.
Start today. Have your agent write your first Skill.
See what your library looks like in three months.
The structure of the next era won’t be discovered — it’ll be built.