From 36a03f75b2d322e8904855a65ed26b8f5417721a Mon Sep 17 00:00:00 2001 From: Ousama Ben Younes Date: Thu, 9 Apr 2026 23:24:14 +0000 Subject: [PATCH 1/2] docs: add Language Support section to smart-explore/SKILL.md (#1651) tree-sitter language docs belonged in smart-explore but were absent; this adds the Bundled Languages table (10 languages) with correct placement. Generated by Claude Code Vibe coded by ousamabenyounes Co-Authored-By: Claude --- plugin/skills/smart-explore/SKILL.md | 21 ++++++++++++ tests/utils/skill-docs-placement.test.ts | 43 ++++++++++++++++++++++++ 2 files changed, 64 insertions(+) create mode 100644 tests/utils/skill-docs-placement.test.ts diff --git a/plugin/skills/smart-explore/SKILL.md b/plugin/skills/smart-explore/SKILL.md index 0f3777e6..19799d86 100644 --- a/plugin/skills/smart-explore/SKILL.md +++ b/plugin/skills/smart-explore/SKILL.md @@ -143,3 +143,24 @@ Use smart_* tools for code exploration, Read for non-code files. Mix freely. | Explore agent | ~39,000-59,000 | Cross-file synthesis with narrative | **4-8x savings** on file understanding (outline + unfold vs Read). **11-18x savings** on codebase exploration vs Explore agent. The narrower the query, the wider the gap — a 27-line function costs 55x less to read via unfold than via an Explore agent, because the agent still reads the entire file. + +## Language Support + +Smart-explore uses **tree-sitter AST parsing** for structural analysis. Unsupported file types fall back to text-based search. + +### Bundled Languages + +| Language | Extensions | +|----------|-----------| +| JavaScript | `.js`, `.mjs`, `.cjs` | +| TypeScript | `.ts` | +| TSX / JSX | `.tsx`, `.jsx` | +| Python | `.py`, `.pyw` | +| Go | `.go` | +| Rust | `.rs` | +| Ruby | `.rb` | +| Java | `.java` | +| C | `.c`, `.h` | +| C++ | `.cpp`, `.cc`, `.cxx`, `.hpp`, `.hh` | + +Files with unrecognized extensions are parsed as plain text — `smart_search` still works (grep-style), but `smart_outline` and `smart_unfold` will not extract structured symbols. diff --git a/tests/utils/skill-docs-placement.test.ts b/tests/utils/skill-docs-placement.test.ts new file mode 100644 index 00000000..f3b46d6c --- /dev/null +++ b/tests/utils/skill-docs-placement.test.ts @@ -0,0 +1,43 @@ +/** + * Regression test for misplaced smart-explore language docs (#1651) + * + * The smart-explore language support section was missing from smart-explore/SKILL.md + * and had previously been in mem-search/SKILL.md (where it doesn't belong). + */ +import { describe, it, expect } from 'bun:test'; +import { existsSync, readFileSync } from 'fs'; +import { join } from 'path'; + +const SKILLS_DIR = join(import.meta.dir, '../../plugin/skills'); + +describe('skill docs placement (#1651)', () => { + it('smart-explore/SKILL.md contains Language Support section', () => { + const path = join(SKILLS_DIR, 'smart-explore/SKILL.md'); + expect(existsSync(path)).toBe(true); + const content = readFileSync(path, 'utf-8'); + + expect(content).toContain('Language Support'); + expect(content).toContain('tree-sitter'); + }); + + it('smart-explore/SKILL.md lists bundled languages', () => { + const content = readFileSync(join(SKILLS_DIR, 'smart-explore/SKILL.md'), 'utf-8'); + + // Core languages must be documented + expect(content).toContain('JavaScript'); + expect(content).toContain('TypeScript'); + expect(content).toContain('Python'); + expect(content).toContain('Go'); + expect(content).toContain('Rust'); + }); + + it('mem-search/SKILL.md does NOT contain tree-sitter or language grammar docs', () => { + const path = join(SKILLS_DIR, 'mem-search/SKILL.md'); + expect(existsSync(path)).toBe(true); + const content = readFileSync(path, 'utf-8'); + + // Language support docs belong in smart-explore, not mem-search + expect(content).not.toContain('tree-sitter'); + expect(content).not.toContain('Bundled Languages'); + }); +}); From e7bf2ac65ad63f8ab706dd5982bbcad30338e29c Mon Sep 17 00:00:00 2001 From: Ousama Ben Younes Date: Fri, 10 Apr 2026 10:52:31 +0000 Subject: [PATCH 2/2] docs: add custom grammar and markdown special support sections to smart-explore/SKILL.md - Add Custom Grammars (.claude-mem.json) section explaining how to register additional tree-sitter parsers for unsupported file extensions - Add Markdown Special Support section documenting heading-based outline, code-fence search, section unfold, and frontmatter extraction behaviors - Expand bundled language test to cover all 10 documented languages plus the plain-text fallback sentence to prevent partial doc regressions Co-Authored-By: Claude --- plugin/skills/smart-explore/SKILL.md | 24 ++++++++++++++++++++++++ tests/utils/skill-docs-placement.test.ts | 24 ++++++++++++++++++------ 2 files changed, 42 insertions(+), 6 deletions(-) diff --git a/plugin/skills/smart-explore/SKILL.md b/plugin/skills/smart-explore/SKILL.md index 19799d86..3bfda66f 100644 --- a/plugin/skills/smart-explore/SKILL.md +++ b/plugin/skills/smart-explore/SKILL.md @@ -164,3 +164,27 @@ Smart-explore uses **tree-sitter AST parsing** for structural analysis. Unsuppor | C++ | `.cpp`, `.cc`, `.cxx`, `.hpp`, `.hh` | Files with unrecognized extensions are parsed as plain text — `smart_search` still works (grep-style), but `smart_outline` and `smart_unfold` will not extract structured symbols. + +### Custom Grammars (`.claude-mem.json`) + +You can register additional tree-sitter grammars for file types not in the bundled list. Create or update `.claude-mem.json` in your project root: + +```json +{ + "grammars": { + ".sol": "tree-sitter-solidity", + ".graphql": "tree-sitter-graphql" + } +} +``` + +Each key is a file extension; each value is the npm package name of the tree-sitter grammar. The grammar must be installed locally (`npm install tree-sitter-solidity`). Once registered, `smart_outline` and `smart_unfold` will parse those extensions structurally instead of falling back to plain text. + +### Markdown Special Support + +Markdown files (`.md`, `.mdx`) receive special handling beyond the generic plain-text fallback: + +- **`smart_outline`** — extracts headings (`#`, `##`, `###`) as the symbol tree. Use it to navigate long documents without reading the full file. +- **`smart_search`** — searches within code fences as well as prose, so queries for function names inside ` ```ts ``` ` blocks work as expected. +- **`smart_unfold`** — expands heading sections rather than function bodies; each section up to the next same-level heading is returned as a chunk. +- **Frontmatter** — YAML frontmatter (lines between leading `---` delimiters) is included in `smart_outline` output under a synthetic `frontmatter` symbol so metadata like `title:` and `description:` is visible without reading the whole file. diff --git a/tests/utils/skill-docs-placement.test.ts b/tests/utils/skill-docs-placement.test.ts index f3b46d6c..d3035195 100644 --- a/tests/utils/skill-docs-placement.test.ts +++ b/tests/utils/skill-docs-placement.test.ts @@ -23,12 +23,24 @@ describe('skill docs placement (#1651)', () => { it('smart-explore/SKILL.md lists bundled languages', () => { const content = readFileSync(join(SKILLS_DIR, 'smart-explore/SKILL.md'), 'utf-8'); - // Core languages must be documented - expect(content).toContain('JavaScript'); - expect(content).toContain('TypeScript'); - expect(content).toContain('Python'); - expect(content).toContain('Go'); - expect(content).toContain('Rust'); + const expectedLanguages = [ + 'JavaScript', + 'TypeScript', + 'TSX / JSX', + 'Python', + 'Go', + 'Rust', + 'Ruby', + 'Java', + 'C', + 'C++', + ]; + + for (const language of expectedLanguages) { + expect(content).toContain(language); + } + + expect(content).toContain('Files with unrecognized extensions are parsed as plain text'); }); it('mem-search/SKILL.md does NOT contain tree-sitter or language grammar docs', () => {