feat(core): dependency traversal for seeAlso cross-skill references#82
feat(core): dependency traversal for seeAlso cross-skill references#82pradeepmouli wants to merge 10 commits into
Conversation
Introduces the cross-reference IR needed for the dep-traversal seeAlso feature: DepSkillRef type, seeAlso? and rootDir? fields on ExtractedSkill. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Discovers dep skills from node_modules, using package.json#skillit.skills explicit list or falling back to skills/*/SKILL.md convention. Exports from refine/index.ts so all consumers get it through @skillit/core. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Covers: missing package.json, no deps, dep not installed, no skills dir, convention discovery, explicit skillit.skills list, missing name field skip, no description, quoted description stripping, multi-dep aggregation, async wrapper. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Both generateCliSkill and generateConfigSkill now call discoverDepSkills and populate skill.rootDir + skill.seeAlso before rendering. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
TypeDoc EVENT_RESOLVE_END (sync): discoverDepSkillsSync(process.cwd()). MCP gen factory: findNearestPackageDir + discoverDepSkills after extract. MCP bundle processEntry: ctx.packageRoot + discoverDepSkills after extract. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Renders ## See Also section between ## NEVER and ## Troubleshooting when skill.seeAlso is populated. Each dep skill is a bold name + backtick path + optional description. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…rage checkW12 warns when a dep has a skill not referenced in ## See Also. Adds +3 to D3 when passing. Improvement suggestion guides users to run `skillit gen` to auto-populate the section. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Minor bump for @skillit/core (new exports + IR fields + audit check), patch bumps for client/typedoc/mcp (wiring only). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Narrow extractFrontmatterField field param to 'name' | 'description' (closes latent regex injection path) - Add existsSync guard for explicit skillit.skills entries (parity with convention path) - Document process.cwd() monorepo limitation in TypeDoc plugin (consistent with plugin convention) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c844c8111b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| // --------------------------------------------------------------------------- | ||
| function checkW12(skill: ExtractedSkill, issues: AuditIssue[], passing: AuditPass[]): void { | ||
| if (!skill.rootDir) { | ||
| passing.push(pass('W12', 'No rootDir set — dep-skill check skipped')); |
There was a problem hiding this comment.
When auditSkill() receives an ExtractedSkill that was not enriched by the new generation paths (for example the current skillit audit sources extract the skill and call auditSkill() without populating rootDir), this branch records W12 as a pass. Since estimateSkillJudgeScore() awards D3 credit for any W12 pass, those audits both suppress the missing ## See Also warning and get dep-skill coverage points even when dependencies expose skills. Treat this as neutral/skipped or populate rootDir before auditing.
Useful? React with 👍 / 👎.
| const pkgDir = process.cwd(); | ||
| skill.rootDir = pkgDir; | ||
| skill.seeAlso = discoverDepSkillsSync(pkgDir); |
There was a problem hiding this comment.
In a TypeDoc monorepo run from the workspace root (the same mode this plugin already supports by scanning packages/* for per-package metadata and READMEs), this sets every generated skill's rootDir to the workspace root and discovers the root package's dependencies for all skills. A package skill such as packages/cli that depends on another workspace package will therefore miss its own dependency skills, or inherit unrelated root-level references, unless TypeDoc is invoked separately from each package.
Useful? React with 👍 / 👎.
| } | ||
|
|
||
| function discoverForDep(pkgDir: string, depName: string): DepSkillRef[] { | ||
| const depDir = join(pkgDir, 'node_modules', depName); |
There was a problem hiding this comment.
This assumes every declared dependency is installed at <pkgDir>/node_modules/<dep>. In npm/Yarn workspaces or hoisted pnpm installs, a valid direct dependency can be resolved from an ancestor node_modules while no package-local entry exists, so discovery returns [] and generated/audited skills omit the required ## See Also references. Use Node package resolution from pkgDir or walk ancestor node_modules directories instead of only checking this fixed path.
Useful? React with 👍 / 👎.
1 participant
Summary
DepSkillReftype andseeAlso?/rootDir?fields toExtractedSkillIR so generated skills can reference sibling skills bundled in direct dependenciesdiscoverDepSkillsSync/discoverDepSkillsinpackages/core/src/refine/dep-skills.ts: readspackage.json#dependencies, checkspkg.skillit.skillsexplicit list first, falls back toskills/*/SKILL.mdconvention, parses frontmatter fornameanddescriptionrenderSeeAlsorenderer — emits## See Alsosection in SKILL.md between## NEVERand## TroubleshootingcheckW12audit check (D3 dimension, +3 pts) that warns when a dependency's bundled skill is not referenced in## See AlsoMotivating case
lspeasy-clidepends onlspeasy-core. An agent using only the CLI skill missed the## NEVERrules that live in the core skill. With this change,skillit genfor lspeasy-cli will emit a## See Alsopointing to the core skill, andskillit auditwill warn if any dep skill is missing from that section.Test Plan
pnpm test— 1163/1163 passing (71 test files, 11 new dep-skills unit tests)pnpm run type-check— clean## See Alsosection appears in a generated skill for a package that has a skillit-enabled dependencyskillit auditW12 warning fires when## See Alsois absent🤖 Generated with Claude Code
https://claude.ai/code/session_01LV8EZLurjZCWsHa9hRMxVc