[frankc]

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".

[vunderba]

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.

[tortilla]

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.

[vunderba]

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.

[1] https://www.anthropic.com/engineering/a-postmortem-of-three-...

[braebo]

For me, it’s pretty reliable until a chat grows too long and it drifts too far away from the start where it reviewed the TOC

[mudkipdev]

I just tag all the relevant documentation and reference code at the beginning of the session

[hatmanstack]

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.

[eggnet]

In general, markdown refers to CommonMark and derivatives now. I’d be surprised if that wasn’t the case here.

[visarga]

> 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.

[mritchie712]

if you've ever worked with Excel + Python, I think this example will drive home the value a bit:

https://github.com/anthropics/skills/blob/main/document-skil...

There are many edge cases when writing / reading Excel files with Python and this nails many of them.

[tortilla]

I manually select my context* (like a caveman) and clear it often. I feel like I have a bit more control and grounding this way.

*I use a TUI to manage the context.

[gonzaman]

Which TUI do you use to manage context?