chore: consolidate skills into one#3672
Conversation
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
Claude Code Review
This repository is configured for manual code reviews. Comment @claude review for a one-time review, or @claude review always to subscribe this PR to a review on every future push.
Tip: disable this comment in your organization's Code Review settings.
github-actions
Bot
added
the
chore
prrao87
left a comment
prrao87
left a comment
There was a problem hiding this comment.
Some concerns with this design, listed below 😅
| - TypeScript API quick reference: `references/typescript/api_reference.md` | ||
| - TypeScript performance guidance: `references/typescript/performance.md` | ||
| 4. Start with `patterns.md` for the selected SDK. Read `api_reference.md` when choosing method names or return collectors. Read `performance.md` when the task involves ingestion, indexing, filtering, query tuning, diagnostics, or large datasets. | ||
| - Column metadata authoring (both SDKs): `references/column_metadata.md` |
There was a problem hiding this comment.
TBH I'm questioning whether we should have everything in a single skill. Having multiple sub-SKILL.md files and a directory for every skill, with a master SKILL.md at the top level would be the right structure for agents, because with the YAML frontmatter on top, it's very token-efficient for an agent to quickly parse through the description, and decide whether or not it wants to go through that skill.
My concern with this design is that all relevant context is buried deep inside these bullet points, and if the model gets "lost in the middle" with context (common in smaller, cheaper models), it can potentially fail to recognize that the relevant markdown file even exists. In this design, only one file has YAML frontmatter, so the agent's model will have to be really good at parsing these finer points as we add more and more skills in the future. It's best to reduce the surface area of failure, and this one seems to increase it.
@dantasse would it make sense to add a domain-specific skill later on called |
There was a problem hiding this comment.
OK, per more discussion, this structure makes sense!
Since column metadata and branch ops are sub-domains of "using LanceDB" — the agent will nearly always enter through the parent skill anyway. Anthropic's documented pattern is a router
SKILL.mdplus per-domain reference files. From the official best-practices doc: for Skills with multiple domains, organize content by domain to avoid loading irrelevant context — when a user asks about sales metrics, Claude only needs to read sales-related schemas, keeping token usage low and context focused. The bundled skill-creator skill I have locally gives the same advice: "When a skill supports multiple domains/frameworks, organize by variant" with aSKILL.mddoing "workflow + selection" and one reference file per variant (skill-creatorSKILL.md, lines 100–109).
Guidelines that shape this:
- Keep your main
SKILL.mdunder 500 lines; move detailed reference material to separate files. Agent Skills- Keep references one level deep from
SKILL.md: Claude may partially read files (e.g., head -100) when they're referenced from other referenced files, resulting in incomplete information. So linkbranch-ops.mddirectly fromSKILL.md, not through an intermediate index. Claude Platform Docs
For reference files longer than 100 lines, include a table of contents at the top.
2 participants
Consolidating skills so we have only one
lancedbskill, making it easier to install and work with, vs. installing and using different skills for "lancedb-column-metadata", "lancedb-branch-ops", etc.Also deleted lancedb-connect, because the new monoskill uses the python/TS APIs so it doesn't need extra handholding to connect to the REST API.
does it work?
Test 1: do some column metadata operations with 1. no skills, 2. our previous baseline lancedb skill, 3. the baseline lancedb skill with the lancedb-column-metadata skill folded in:
without column-metadata-specific content, it failed because it wrote keys like
descriptioninstead oflancedb:description. That's pretty undiscoverable without the skill.Test 2: do some simple branch operations with 1. no skills, 2. our previous baseline lancedb skill, 3. the combined skill (in this PR):
Test 3: run everything, with the lancedb (original) skill, lancedb(original) + all the separate skills, and lancedb3-incl-columns-branches
("lancedb3-incl-columns-branches" is the combined skill in this PR, all-separate is using the four separate skills.)
For overall performance, it helps to have the specialized skills for metadata and branching; doesn't really matter whether they're separate skills or all together. Also doesn't matter much whether it's REST or Python. So let's merge these skills to make it easier for users.