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.

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

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

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

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.

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

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.

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.

Which TUI do you use to manage context?

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