Agent Skills: opensrc-research

opensrc-research

Quickstart

One command grounds an answer: resolve the package's real source path, then search it.

rg "useQuery" "$(opensrc path @tanstack/react-query)"

opensrc path prints the on-disk checkout (fetching on first use); rg greps it for the symbol you're about to make a claim about. Everything below is variations on this shape.

When to fire

Fire this skill whenever the next answer would otherwise be a guess about how a dependency behaves. Signals:

• "Does library X support Y?" / "How does X actually do Y?"
• "Is the doc claim about X accurate?"
• "Grep for Z in package W"
• Borderline confidence answering an API question — about to write [unverified]
• Code under review imports a package and you want to ground a review comment in actual source

The grounded-answer workflow

1. Identify the package shape:

   | Shape | Form | Example | |-------|------|---------| | npm package | bare name | opensrc path zod | | PyPI package | pypi: prefix | opensrc path pypi:requests | | Rust crate | crates: prefix | opensrc path crates:serde | | NuGet package | use the wrapper | "${CLAUDE_PLUGIN_ROOT}/bin/nuget-opensrc" path Microsoft.Extensions.Logging | | GitHub repo | owner/repo (drifts with main) | opensrc path open-telemetry/opentelemetry-dotnet | | GitHub repo at commit | owner/repo#<sha> (pinned) | opensrc path dotnet/runtime#abc123 |

2. Fetch and grep:

   # NuGet (commit-pinned — preferred for .NET work):
   PKG_PATH="$("${CLAUDE_PLUGIN_ROOT}/bin/nuget-opensrc" path Microsoft.AspNetCore.Authentication.JwtBearer)"
   rg "JwtBearerEvents" "$PKG_PATH"
   
   # npm / PyPI / crates / GitHub:
   rg "parseAsync" "$(opensrc path zod)"
   

3. Cite findings as file:line references, not paraphrases. The whole point is grounding — quote what's actually in the source.

4. If using bare GitHub form, the result is the default branch and drifts with main. To pin to a specific tag after fetching:

   cd "$(opensrc path open-telemetry/opentelemetry-dotnet)" && git checkout v1.10.0
   

When NOT to fire

• Stdlib / language built-ins — faster: python -c "import inspect; print(inspect.getsource(...))" or dotnet decompile.
• Closed-source NuGet packages — no GitHub repository.url metadata, wrapper will error out explicitly.
• Documented behavior is sufficient — if the question is "what does the doc say X does" rather than "what does X actually do", docs are faster.
• You already have the cached path — opensrc list shows what's already on disk; no re-fetch needed.

Anti-patterns to avoid

• Guessing then marking [unverified] when opensrc would have given the answer in one command. The marker is for when verification is impossible, not when it's mildly inconvenient.
• Resolving NuGet packages via plain opensrc path owner/repo without commit-pinning — silently reads main and the source you grep may not be what the package shipped. Use the wrapper for NuGet.
• Falling back to projectUrl if NuGet metadata lacks repository.url — projectUrl points at marketing pages (e.g. https://dot.net/) and lies about source location. The wrapper refuses to use it; you should too.

Cache hygiene

• opensrc list — see what's cached
• opensrc remove <pkg> — drop one
• opensrc clean — drop everything (regret-only-if-no-network)
• Cache lives at <OPEN_SRC_CACHE_DIR>/repos/github.com/<owner>/<repo>/<ref>/
• Microsoft repos (especially dotnet/dotnet, the unified VMR) are large (~3-4 GB cloned). Don't pre-warm aggressively.