So far I am in the skeptic camp on this. I don't see it adding a lot of value to my current claude code workflow which already includes specialized agents and a custom mcp to search indexed mkdocs sites that effectively cover the kinds of things I would include in these skills file. Maybe it winds up being a simpler, more organized way to do some of this, but I am not particularly excited right now.
I also think "skills" is a bad name. I guess its a reference to the fact that it can run scripts you provide, but the announcement really seems to be more about the hierarchical docs. It's really more like a selective context loading system than a "skill".
I'm inclined to agree. I've read through the Skill docs and it looks like something I've been doing all along - though I informally referred to it as the "Table of Contents" approach.
Over time I would systematically create separate specialized docs around certain topics and link them in my CLAUDE.md file but noticeably without using the "@" symbol which to my understanding always causes CLAUDE to ingest the linked files resulting in unnecessarily bloating your prompt context.
So my CLAUDE md file would have a header section like this:
# Documentation References
- When adding CSS, refer to: docs/ADDING_CSS.md
- When adding or incorporating images, refer to: docs/ADDING_IMAGES.md
- When persisting data for the user, refer to: docs/STORAGE_MANAGER.md
- When adding logging information, refer to: docs/LOGGER.md
It seems like this is less of a breakthrough and more an iterative improvement towards formalizing this process from a organizational perspective.
How consistently do you find that Claude Code follows your documentation references? Like you work on a CSS feature and it goes to ADDING_CSS.md? I run into issues where it sometimes skips my imperative instructions.
It's funny you mention this - for a while I was concerned that CC wasn't fetching the appropriate documentation related to the task at hand (coincidentally this was around Aug/Sept when Claude had some serious degradation issues [1]), so I started adding the following to the beginning of each specialized doc file:
When this documentation is read, please output "** LOGGING DOCS READ **" to the console.
These days I do find that the TOC approach works pretty well though I'll probably swap them over to Skills to see if the official equivalent works better.
That's exactly what it is - formalizing and creating a standard induces efficiency. Along with things like AGENTS.md, it's all about standardization.
What bugs me: if we're optimizing for LLM efficiency, we should use structured schemas like JSON. I understand the thinking about Markdown being a happy medium between human/computer understanding but Markdown is non-deterministic for parsing. Highly structured data would be more reliable for programmatic consumption while still being readable.
> and a custom mcp to search indexed mkdocs sites that effectively cover the kinds of things I would include in these skills file
Search and this document base pattern are different. In search the model uses a keyword to retrieve results, here the model starts from a map of information, and navigates it. This means it could potentially keep context better, because search tools have issues with information fragmentation and not seeing the big picture.
I also think "skills" is a bad name. I guess its a reference to the fact that it can run scripts you provide, but the announcement really seems to be more about the hierarchical docs. It's really more like a selective context loading system than a "skill".