https://docs.claude.com/en/docs/claude-code/claude_code_docs...
This is driven by instructions in the Claude Code system prompt:
> When the user directly asks about Claude Code (eg. "can Claude Code do...", "does Claude Code have..."), or asks in second person (eg. "are you able...", "can you do..."), or asks how to use a specific Claude Code feature (eg. implement a hook, or write a slash command), use the WebFetch tool to gather information to answer the question from Claude Code docs. The list of available docs is available at https://docs.claude.com/en/docs/claude-code/claude_code_docs....
Screenshot and notes here: https://simonwillison.net/2025/Oct/24/claude-code-docs-map/
I had the post pretty much done, went on vacation for a week, and Claude Skills came out in the interim.
That being said Skills are indeed an implementation of the patterns possible with linking, but they are narrower in scope than what's possible even with MCP Resources if they were properly made available to agents (e.g. dynamic construction of context based on environment and/or fetching from remote sources).
[tools] web_search = true
Though in this case, I did read the original article.
Not an exact science yet.
It seems to think they are a vendor lockin play by Anthropic, running as an opaque black box.
To rebut their four complaints:
1. "Migrating away from Anthropic in the future wouldn't just mean swapping an API client; it would mean manually reconstructing your entire Skills system elsewhere." - that's just not true. Any LLM tool that can access a filesystem can use your skills, you just need to tell it to do so! The author advocates for creating your own hierarchy of READMEs, but that's identical to how skills work already.
2. "There's no record of the selection process, making the system inherently un-trustworthy." - you can see exactly when a skill was selected by looking in the tool logs for a Read(path/to/SKILL.md) call.
3. "This documentation is no longer readily accessible to humans or other AI agents outside the Claude API." - it's markdown files on disk! Hard to imagine how it could be more accessible to humans and other AI agents.
4. "You cannot optimize the prompt that selects Skills. You are entirely at the mercy of Anthropic's hidden, proprietary logic." - skills are selected by promoting driven by the system prompt. Your CLAUDE.md file is injected into that same system prompt. You can influence that as much as you like.
There's no deep, proprietary magic to skills. I frequently use claude-trace to dig around in Claude Code internals: https://simonwillison.net/2025/Jun/2/claude-trace/ - here's an example from last night: https://simonwillison.net/2025/Oct/24/claude-code-docs-map/
The closing section of that article revels where that author got confused They said: "Theoretically, we're losing potentially "free" server-side skill selection that Anthropic provides."
Skills are selected by Claude Code running on the client. They seem to think the it's a model feature that's proprietary to Anthropic - it's not, it's just another simple prompting hack.
That's why I like skills! They're a pattern that works with any AI agent already. Anthropic merely gave a name to the exact same pattern that this author calls "Agent-Agnostic Documentation" and advocates for instead.
This used to work great two years ago when chatgpt first got the Web browsing feature. Nowadays, no eyeballs on ads: no content.
"The irony is they trained their model on so much porn even barely NSFW prompts get flagged because Grok the Goon Commander thinks a simple fully-clothed lapdance requires a visible massive dong being thrusted up her piehole."
https://old.reddit.com/r/grok/comments/1ofd6xm/the_irony_is_...
We don't need MCPs for this, just make a tool that uses Trafilatura to read web pages into markdown and create oldschool server side web UIs, and let the agents curl them.
...until now. It seems they finally found their problem.
> This never worked in practice. Building hypertext APIs was too cumbersome and to actually consume APIs a human needed to understand the API structure in a useful manner anyway.
Every time I read one of these comments I feel like DiCaprio's character in Inception going "but we did grow old together." HATEOAS worked phenomenally. Every time you go to a webpage with buttons and links in HTML that describe what the webpage is capable of (its API, if you will), you are doing HATEOAS [0]. That this interface can be consumed by both a user (via the browser) and a web scraper (via some other program) is the foundation of modern web infrastructure.
It's a little ironic that the explosion of information made possible by HATEOAS happened while the term it self largely got misunderstood, but such is life. Much like reclaiming the proper usage of its close cousin, "REST," using HATEOAS correctly is helpful for properly identifying what made the world's largest hypermedia system successful—useful if you endeavor to design a new one [1].
[0] https://htmx.org/essays/hateoas/
[1] https://unplannedobsolescence.com/blog/why-insist-on-a-word/
If we jump down to the bolts and nuts, let's say on a json API, it's about including extra attributes/fields in your json response that contain links and information of how to continue. These attributes have to be blended with your other real attributes.
For example if you just created a resource with a POST endpoint, you can include a link to GET the freshly created resource ("_fetch"), a link to delete it ("_delete"), a link to list all resources of the same collection ("_list"), etc...
Then the client application is supposed to automatically discover the API's functionality. In case of a UI, it's supposed to automatically discover the API's functionality and build a presentation layer on the fly, which the user can see and use. From our example above, the UI codebase would never have a "delete" resource button, it would have a generic button which would be created and placed on the UI based on the _delete field coming back from the API
The front end ui was entirely driven, ui and functionality exposed by the data/action payload.
I'm still not sure if it's because of the implementation or because there is something fundemental.
I came away from that thinking that the db structure, the dag and data flow is what's really important for thinking about any problem space and any ui considerations should be not first class.
But I'm not a theorist, I just found a specific real, real formal working implementation in prod to be not great, it's a little hard even now to understand why.
Maybe it just works for purely text interfaces, adding any design or dynamic interaction causes issues.
I think maybe it's that the data itself should be first class, that well typed data should exist and a system that allows any ui and behavior to be attached to that data is more important than an api saying what explicit mutations are allowed.
If I was to explore this, I think folder and files, spreadsheet, dbs, data structures, those are the real things and the tools we use to mutate them are second order and should be treated as such. Any action that can be done on data should be defined elsewhere and not treated as being the same importance, but idk, that's just me thinking outloud.
The web is also a real product, one that's (when not bloated with adtech) capable of being fast and easy to develop on. That other people have tried to do HATEOAS and failed to make it nice is part of why it's so useful to acknowledge as valid the one implementation that has wildly succeeded.
The missing piece was having machines that could handle enough ambiguity to "understand" the structure of the API without it needing to be generic to the point of uselessness.
The creator of REST, Roy Fielding, literally said this loud and clear:
> REST APIs must be hypertext-driven
> What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint? In other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period.
— https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert...
I think of all the people in the world, the creator of REST gets to say what is and isn’t REST.
The concept of a HATEOAS API is also very simple: the API is defined by a communication protocol, 1 endpoint, and a series of well-defined media types. For a website, the protocol is HTTP, that 1 endpoint is /index.html, and the media types are text/html, application/javascript, image/jpeg, application/json and all of the others.
The purpose of this system is to allow the creation of clients and servers completely independently of each other, and to allow the protocols to evolve independently in subsets of clients and servers without losing interoperability. This is perfectly achieved on the web, to an almost incredible degree. There has never been, at least not in the last decades, a big where, say, Firefox can't correctly display pages severed by Microsoft IIS: every browser really works with every web server, and no browser or server dev even feels a great need to explicitly test against the others.
Browsers can alter a webpage with your chosen CSS, interactively read webpages out loud to you, or, as is the case with all the new AI browsers, provide LLM powered "answers" about a page's contents. These are all recontextualizations made possible by the universal HATEOAS interface of HTML.
I guess someone interested would have to read the original work by Roy (who seems to have come up with the term) to find out which opinion is true
HATEOAS and by-the-book REST don’t provide much practical value for writing applications. As the article says, a human has to read the spec, make sense of each endpoint’s semantics, and write code specific to those semantics. At that point you might as well hardcode the relevant URLs (with string templating where appropriate) rather than jumping through hoops and pretending every URL has to be “discovered” on the off chance that some lunatic will change the entire URL structure of your backend but somehow leave all the semantics unchanged.
The exception, as the article says, is if we don’t have to understand the spec and write custom code for each endpoint. Now we truly can have self-describing endpoints, and HATEOAS moves from a purist fantasy to something that actually makes sense.
