agentleFS
omidnwomidnw/my-skills/skills/research-and-reuse/SKILL.md

research-and-reuse

Skill0 starsChanged 13 days agoMITView on GitHub

Research authoritative sources before implementing unfamiliar domain-expert or algorithm-heavy code, and evaluate maintained existing packages before writing custom implementations. Use when working on sensor/signal processing, detection, audio DSP, crypto, networking protocols, ML, or media algorithms, when integrating an unfamiliar library/API/SDK, when deciding package versus custom implementation, or when the user says "research this first", "use npm packages", "don't rebuild the wheel". Prefer official documentation and proven dependencies; when a dedicated documentation skill exists for the technology (e.g. tauri-v2-docs), use that skill first; if concrete questions remain unresolved after research, delegate to the external-ai-consult skill.

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 6 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Keep confidential code, identifying project details and private errors out of external queries.

    line 50
  2. Very specific:

    If the session has a web-search tool, it can reach the official docs / npm pages.

    line 52
  3. Distinctive:

    Name the unknowns: Write down the 2–5 sharp, self-contained questions that, if answered, would de-risk the implementation: which algorithm …

    line 58
  4. Distinctive:

    Research tier A — the web (when available): Use WebSearch / WebFetch against official sources: the language's docs, the npm registry page, …

    line 62
  5. Distinctive:

    Decide: package vs custom: Prefer the package unless the logic is trivial AND safe to hand-roll, or every candidate package is unmaintained …

    line 74
  6. Distinctive:

    Verify in this repo: Add only the selected required dependency using the project's package manager/version policy, build, and exercise the …

    line 77
  7. Distinctive:

    Record the choice: Use a short code comment only where project conventions permit and it explains a non-obvious decision.

    line 80
  8. Distinctive:

    Follow the repository's version policy and lockfile: Prefer reproducible resolved versions, but do not rewrite the project's existing range …

    line 98

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Research First, Reuse Packages

Purpose

Two behaviors that keep a codebase bug-light:

  1. Research before you implement. Domain-expert logic (sensor processing, audio analysis, crypto, networking, ML) is full of subtle failure modes that change over time. Never write it from training-data memory — get the current, proven approach first.
  2. Reuse before you rebuild. A well-maintained package has been exercised by thousands of real users; a freshly written implementation has only your tests. For non-trivial problems, depending on a package is the bug-reduction strategy, not a shortcut.

When to use

  • Adding or rewriting algorithm-heavy / domain-expert code (sensor or signal processing, pose/detection logic, audio DSP, crypto, media handling, network protocols, ML).
  • Deciding between "implement it" and "use a package" for any feature.
  • Integrating an unfamiliar library, API, or SDK (unknown flags, current versions, platform quirks).
  • The user explicitly asks for research or package reuse ("research this first", "use npm packages", "don't rebuild the wheel").
  • Technologies with a dedicated documentation skill (e.g. tauri-v2-docs): that skill owns API/config/CLI lookups — use research-and-reuse for broader implementation research, package selection, or unresolved questions outside its scope.

Preconditions

  • Keep confidential code, identifying project details and private errors out of external queries. Prefer local installed documentation/source first; public research uses generic terms. Any external AI fallback must pass external-ai-consult's privacy gate.
  • If the session has a web-search tool, it can reach the official docs / npm pages. When research is not decisive, the external-ai-consult skill handles asking an external AI (automatic tool or copy-paste block).

Workflow

  1. Name the unknowns. Write down the 2–5 sharp, self-contained questions that, if answered, would de-risk the implementation: which algorithm / package is the current best practice, exact API shapes, version numbers, stack constraints, known pitfalls.
  2. Research tier A — the web (when available). Use WebSearch / WebFetch against official sources: the language's docs, the npm registry page, the library's GitHub README and docs, the maintainer's changelog. Read the actual docs; do not stop at search-result summaries.
  3. Research tier B — external AI consult (when tier A isn't decisive). Invoke the external-ai-consult skill — it owns the question format, delivery procedure, fallback, and decline behavior. Incorporate returned answers before implementation; otherwise follow that skill's fallback outcome instead of inventing a separate policy here.
  4. Search for a package before writing custom code. On npm/GitHub, look for a maintained package that solves the problem. Evaluate it against the Rules below (maintenance, license, compatibility, weight).
  5. Decide: package vs custom. Prefer the package unless the logic is trivial AND safe to hand-roll, or every candidate package is unmaintained / license-incompatible / too heavy for the need.
  6. Verify in this repo. Add only the selected required dependency using the project's package manager/version policy, build, and exercise the real code path: the project's typecheck / lint / tests, and the actual runtime flow. Proof it works here beats a README that says so.
  7. Record the choice. Use a short code comment only where project conventions permit and it explains a non-obvious decision; note the chosen package (or the reason a package was rejected) plus the research source in the change summary, so the next agent does not re-litigate it.

Rules

  • Prefer an existing, maintained package over new code for domain-expert logic (sensors, DSP, crypto, ML, media, networking). Do not rebuild the wheel.
  • Never copy package internals into the repo — depend on the package so security/behavior updates flow in. (The one exception: small, clearly- licensed, vendored helper code with a comment saying where it came from.)
  • Check before adding a dependency: maintenance/security response and compatibility matter more than an arbitrary publish-age cutoff; mature stable libraries can be healthy without a release in the last year. Consider weekly downloads, license compatible (MIT / Apache-2.0 / BSD / OFL fine; be careful with GPL/AGPL for a distributed or proprietary app), TypeScript types present or easy to add, compatible with the project's stack (framework/version; no bare Node built-ins on the frontend, no native addons in a Tauri-like guest unless packaged).
  • Follow the repository's version policy and lockfile. Prefer reproducible resolved versions, but do not rewrite the project's existing range policy or package manager incidentally. Exact pins are required when the project or deployment needs them.
  • The global "fewer dependencies" principle still applies — it is the tie-breaker between equivalent candidates, and it still forbids pulling a 500 KB library for a 5-line need. Research-reuse never means dependency bloat.
  • Verify external info before relying on it. AI answers, search snippets, and READMEs are unverified claims. Check the official docs and run the code in this repo's environment before trusting it.
  • If research contradicts existing code, surface it — explain the discrepancy to the user instead of silently rewriting working behavior.

Common mistakes

  • Writing algorithm code from training-data memory (e.g. rolling your own heuristics) — subtle accuracy and battery bugs; research the current best practice and library first.
  • Adding a stale or unmaintained package, then shipping a broken feature built on it.
  • Picking a frontend package that imports Node built-ins — it fails the frontend build with confusing module errors.
  • Copy-pasting a package's code into the repo to "avoid the dependency" — now the bug fixes never arrive.
  • Trusting an AI answer or a package README without ever running the code.
  • Over-engineering: pulling a large library when a tiny, maintained one (or a few lines of verified code) suffices.
  • Ignoring license — shipping a GPL/AGPL dependency in a proprietary app.

Validation

  • The feature passes the project's checks: its typecheck, lint, and relevant test suites.
  • Any added dependency exists in the manifest and lockfile under the project's established version policy; choosing a verified custom implementation does not require adding a dependency.
  • The real code path actually ran (unit test or manual run of the feature), not just type-checked.
  • The research step visibly happened: the change summary cites either a web source (official docs / npm page) or an external-AI consult that informed the implementation.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.