5 ms·

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

by frankc 1y ago

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

hatmanstack 1y ago
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 1y ago
  In general, markdown refers to CommonMark and derivatives now. I’d be surprised if that wasn’t the case here.
tortilla 1y ago
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 1y ago
  Which TUI do you use to manage context?
vunderba 1y ago
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 1y ago
  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.
  - braebo 1y ago
    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
  - vunderba 1y ago
    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-recent-issues https://www.anthropic.com/engineering/a-postmortem-of-three-...
mritchie712 1y ago
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-skills/xlsx/SKILL.md 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.
visarga 1y ago
> 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.

by frankc 1y ago

hatmanstack 1y ago

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 1y ago
In general, markdown refers to CommonMark and derivatives now. I’d be surprised if that wasn’t the case here.

tortilla 1y ago

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 1y ago
Which TUI do you use to manage context?

vunderba 1y ago

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 1y ago
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.
- braebo 1y ago
  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
- vunderba 1y ago
  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-recent-issues https://www.anthropic.com/engineering/a-postmortem-of-three-...

mritchie712 1y ago

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-skills/xlsx/SKILL.md 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.

visarga 1y ago

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