Skip to content
Back to search

pavedpath-code

PavedPath Code: reusable Skill for finding proven implementation paths from GitHub and open-source evidence

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jia-ethan--pavedpath-code/badge.svg)](/listings/jia-ethan--pavedpath-code)

HTML

<a href="/listings/jia-ethan--pavedpath-code"><img src="/api/listings/jia-ethan--pavedpath-code/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

安装到你的智能体 active skill / instructions 目录。下面示例使用 `~/.codex/skills`;Claude Code、Cursor Agent、ChatGPT Agent 或其他智能体请按自己的本地指令目录改写路径:

mkdir -p ~/.codex/skills
git clone https://github.com/Jia-Ethan/pavedpath-code.git \
  ~/.codex/skills/pavedpath-code

更新已有安装:

git -C ~/.codex/skills/pavedpath-code pull --ff-only

建议按需安装并登录 GitHub CLI:

gh auth status

这个 Skill 不绑定任何具体模型或智能体。它吸收了多 agent 搜索建议,但保持平台无关;真正的约束在于问题拆分、证据链接、去重、controller 复核和本地验证。

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 136 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: pavedpath-code
  3. description: PavedPath Code is the code-focused edition of PavedPath. It helps agents solve software engineering problems by finding proven implementation paths from GitHub repositories, issues, pull requests, discussions, code examples, release notes, and open-source evidence.
  4. ---
  5. # PavedPath Code
  6. PavedPath Code(代码版)helps agents avoid reinventing solutions for software engineering problems. It searches GitHub and open-source evidence for proven implementation paths, then adapts the strongest pattern to the local codebase with minimal, verifiable changes.
  7. Use GitHub as a primary evidence source, not as a link dump. The goal is to define the local code problem, find paths already walked in public repositories, issues, pull requests, discussions, examples, release notes, and source code, evaluate the strength of that evidence, then translate the strongest pattern into a small local fix, implementation path, or verification plan.
  8. This is the code-focused edition of PavedPath. Do not broaden it into the future general-purpose PavedPath. It is for software engineering work: bugs, runtime errors, build/test/deploy failures, dependency issues, framework or API usage, integration blockers, implementation patterns, engineering tool selection, and open-source solution adaptation.
  9. ## When to Use
  10. - Runtime, build, test, deploy, package, SDK, API, dependency, framework, or integration errors.
  11. - A feature implementation is blocked by an unclear edge case, missing usage pattern, version behavior, or uncertain API contract.
  12. - A local issue resembles something that maintainers or other open-source users may have resolved in issues, PRs, examples, code, release notes, or discussions.
  13. - The user asks whether GitHub or open-source projects have already solved a concrete engineering problem.
  14. - Mature implementation examples or reusable projects would reduce uncertainty for one specific capability.
  15. - The answer should compare suitable GitHub repositories and explain how to adapt one proven path locally.
  16. Do not use PavedPath Code for copy edits, purely local refactors where the codebase already dictates the answer, non-code life decisions, self-media workflows, study methods, consumer purchasing decisions, or requests that explicitly forbid web/GitHub research. Do not inspect private repositories unless the user explicitly scopes and authorizes that access.
  17. ## Default Workflow
  18. 1. **Frame the local code problem first.** Capture the goal, symptom, error signature, reproduction path, versions, runtime, dependency/framework names, recent changes, constraints, and attempted fixes. If a discoverable fact is missing, inspect local files/logs before asking.
  19. 2. **Choose the evidence mode.** For errors/regressions, search issues, PRs, releases, and code first. For capability or tool needs, search repository candidates first. For feature implementation, use both repository candidates and issue/PR/code evidence.
  20. 3. **Evaluate subagent usefulness.** Before substantial GitHub research, decide whether conditional subagent work would improve breadth, evidence quality, or review coverage. If not using subagents, state the reason briefly when reporting the search path.
  21. 4. **Create targeted searches.** Prefer exact error text, package/API names, version numbers, framework + symptom, file names, config keys, stack trace fragments, failing command names, or capability + framework/runtime/API names.
  22. 5. **Find suitable GitHub projects when relevant.** Prefer high-fit, high-Star, active, non-archived repositories with clear licenses and real examples. Lower the Star threshold when the high-Star set is too broad or misses the exact problem.
  23. 6. **Search open-source evidence surfaces.** Use issues, PRs, discussions, code, examples, release notes, and official project docs within relevant open-source repos. Repository search is required when a project itself may solve the problem.
  24. 7. **Rank by problem fit first, with Stars as a maturity signal.** A high-Star repository is a strong candidate for inspection, but maintainer-confirmed issues, merged PRs, released fixes, official examples, and exact matching code beat popular adjacent projects. Use [research-rubric.md](references/research-rubric.md) when ranking matters.
  25. 8. **Deep-read the strongest projects and evidence.** Use [extraction-playbook.md](references/extraction-playbook.md) to extract project basics, reusable surfaces, root cause or implementation pattern, version constraints, risks, adaptation boundaries, and verification steps.
  26. 9. **Translate to local work with minimal adaptation.** Preserve the proven workflow, API, configuration shape, or architecture where it fits. Adapt only the parts required by the user's local interfaces, configuration, data/auth model, deployment target, or language/runtime.
  27. 10. **Verify before claiming success.** Use tests, builds, reproduction commands, real requests, logs, browser checks, or manual inspection appropriate to the local problem.
  28. 11. **If evidence is weak, say so.** Do not stretch weak matches into a confident recommendation. Mark the recommendation as first-principles or local-only when open-source evidence is insufficient.
  29. ## Subagent / Parallel Research Guidance
  30. Subagents are conditional research aids, not a default requirement. The controller remains responsible for problem framing, scope control, evidence ranking, local adaptation, and final verification.
  31. Use subagents when at least one of these applies:
  32. - The problem spans 2+ independent ecosystems, frameworks, languages, tools, deployment surfaces, or GitHub communities.
  33. - Repository discovery needs broad candidate coverage across multiple query families.
  34. - Issue, PR, discussion, code, release, and example evidence can be split cleanly by project, version, or search surface.
  35. - A final recommendation benefits from independent evidence review, risk review, or candidate rejection review.
  36. Do not use subagents when any of these applies:
  37. - The task is a narrow error with one obvious package, repository, API, or maintainer surface.
  38. - Local repository context, logs, config, or reproduction details must be understood before external research can be scoped safely.
  39. - GitHub rate limits, authorization boundaries, private repositories, secrets, production data, or sensitive logs would make delegation risky.
  40. - Subagents would mostly duplicate the same searches or edit the same local files.
  41. When using subagents, the controller must:
  42. - Define each subagent's query family, repository scope, evidence surface, constraints, allowed write scope, and expected output.
  43. - Require direct links, verified metadata, problem-fit rationale, risk notes, and explicit rejection reasons.
  44. - Keep subagents read-only unless a separate implementation phase has a narrow allowed write scope.
  45. - Merge and deduplicate results before ranking; do not count repeated reports of the same issue, PR, code path, or repository as independent evidence.
  46. - Directly verify the strongest claims with `gh`, source reads, tests, logs, real requests, or official docs before finalizing.
  47. ## GitHub CLI First
  48. Use the GitHub CLI (`gh`) as the default search and inspection surface. Prefer `gh search repos`, `gh search issues`, `gh search prs`, `gh search code`, `gh repo view`, `gh issue view`, `gh pr view`, and `gh api` before browser scraping or custom scripts. Do not add or rely on bundled search scripts for this skill.
  49. Use these short command templates as starting points, then adjust the query, repo, fields, and limits to the local problem:
  50. ```bash
  51. gh search repos "<query>" --archived=false --sort stars --order desc --limit 10 --json fullName,url,description,stargazersCount,forksCount,language,license,pushedAt,isArchived,openIssuesCount
  52. gh search issues "<query>" --repo owner/repo --sort updated --order desc --limit 10 --json title,url,state,updatedAt,commentsCount,repository,body
  53. gh search prs "<query>" --repo owner/repo --merged --sort updated --order desc --limit 10 --json title,url,state,updatedAt,commentsCount,repository,body
  54. gh search code "<query>" --repo owner/repo --limit 10 --json path,url,repository,sha
  55. gh repo view owner/repo --json nameWithOwner,url,description,stargazerCount,forkCount,licenseInfo,primaryLanguage,pushedAt,repositoryTopics,homepageUrl
  56. gh api -X GET search/repositories -f q='<query> archived:false' -f sort=stars -f order=desc
  57. ```
  58. Only run `gh auth status` when a command fails with 403, 429, a private repository authorization error, or an explicit `gh` not-authenticated message. If GitHub returns 403/429, inspect the emitted rate-limit or authorization context before retrying, reducing breadth, or switching endpoints. Do not paste or persist tokens, cookies, private repository contents, or credentials in prompts, files, logs, or memory.
  59. ## Search Strategy
  60. - Start narrow: exact error string, exception class, CLI output, package + method name, config key, or stack trace fragment.
  61. - Add constraints: package/framework version, language, platform, deployment target, bundler, database, auth provider, or runtime.
  62. - Search surfaces in this order when relevant: issues/PRs/discussions, merged fixes, release notes/changelog, examples/templates, source code, then repository-level candidates.
  63. - For implementation blockers without an error, search for the desired capability plus framework/runtime/API names.
  64. - For public platform data needs such as trends, hot lists, topic search, or engagement metrics, do not start with visual browser scraping. First look for reusable public endpoints, open-source crawlers, archived datasets, and API field evidence; then verify the chosen source with a minimal real request and clearly separate anonymous hot-list data from logged-in search/topic data.
  65. - For reusable project discovery, search repositories sorted by Stars, then deep-read only candidates that match the local problem. Record Stars, forks, language, license, activity, and basic content.
  66. - Demote matches that are old, version-mismatched, archived, unresolved, speculative, or based only on user guesses.
  67. - Use Stars/forks only as supporting maturity context and tie-breakers among similarly fitting repositories. They do not override problem fit, maintainer-confirmed evidence, merged PRs, release notes, official examples, or reproducible code.
  68. - For security, auth, payments, infrastructure, or production operations, cross-check open-source findings against current official docs or repositories when facts may have changed.
  69. ## Evidence Standard
  70. For each serious evidence item, identify:
  71. - exact match: same error, behavior, API, version, environment, or workflow;
  72. - evidence strength: maintainer confirmation, merged PR, released fix, reproducible code example, test fixture, or repeated independent reports;
  73. - applicability: what conditions must match locally for the solution to apply;
  74. - implementation value: patch, config, API usage, dependency version, workflow, test, or operational pattern worth adapting;
  75. - project basics when a repository is a candidate: name, URL, Stars, forks, language, license, activity, basic content, fit rationale, and adaptation cost;
  76. - risk: stale version, unresolved issue, unsafe workaround, license concern, security/privacy impact, deployment mismatch, or overbroad change.
  77. ## Output Contract
  78. When PavedPath Code materially affects the answer, include:
  79. - local problem profile: goal, symptom/error, versions/environment, and local constraints;
  80. - search path: queries or discovery methods used, GitHub/open-source surfaces searched, and whether subagents were used or skipped;
  81. - subagent trace when subagents were used: each subagent's scope, evidence surfaces, key findings, rejected candidates, deduplication results, and which claims the controller directly verified;
  82. - project candidates when a GitHub project itself is relevant: repo link, Stars, forks, language, license, activity, basic content, match rationale, and how it can be used locally;
  83. - key evidence: links to issues, PRs, code, examples, releases, or repos, with match rationale;
  84. - recommended solution: what to reuse directly, what to adapt locally, what to avoid copying, and why it fits;
  85. - rejected or risky options: why they do not apply or need caution;
  86. - verification standard: test, build, reproduction command, real request, or manual check required to confirm the fix;
  87. - confidence label when evidence is weak or no strong open-source solution was found.
  88. When repository-level solutions are relevant, include a compact project table. For pure issue/PR/code fixes, the table is optional, but include repository context if it affects trust or applicability.
  89. Do not answer with only links, Stars, or popularity rankings. Do not write "common GitHub pattern" without linked evidence. Do not let external examples override local constraints.
  90. For website, SaaS, landing-page, theme, or frontend-template candidate research, include both the repository URL and the live preview/demo URL for every serious candidate. If no preview is available or verified, state that explicitly and downgrade the candidate.
  91. ## Migration Note
  92. `github-solution-research` has been renamed to **PavedPath Code**. Previous behavior is preserved; this is a naming and positioning update for the code-focused edition of PavedPath. New installations should use the `pavedpath-code` skill name and the active skill/instruction directory of the target agent runtime.
  93. ## Safety Boundaries
  94. - Prefer reading patterns and reusing existing public interfaces over copying code. If code reuse is necessary, check the license and keep attribution/obligation risks visible.
  95. - Avoid large rewrites of an existing open-source solution. Keep its proven flow intact and make only the local adaptations required for the user's problem.
  96. - Avoid large verbatim excerpts from repositories, READMEs, issues, PRs, or documentation.
  97. - Do not save GitHub tokens, cookies, private repository contents, or credentials in outputs, logs, skills, or memory.
  98. - Do not pass tokens, cookies, private repository contents, sensitive logs, secrets, production data, or credentials to subagents.
  99. - If network access is unavailable, state that open-source research could not be performed and mark the recommendation as local-only.
README.md · README · 374 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <!-- markdownlint-disable MD013 MD033 -->
  2. <h1 align="center">PavedPath Code</h1>
  3. <p align="center">
  4. PavedPath Code(代码版)is a reusable Skill for finding proven implementation paths from GitHub and open-source evidence, then adapting them to local software engineering problems.
  5. </p>
  6. <p align="center">
  7. <a href="#复制给智能体安装">复制给智能体安装</a>
  8. ·
  9. <a href="#简体中文">简体中文</a>
  10. ·
  11. <a href="#english">English</a>
  12. ·
  13. <a href="#migration">Migration</a>
  14. ·
  15. <a href="#license">License</a>
  16. </p>
  17. <p align="center">
  18. <img alt="Reusable Skill" src="https://img.shields.io/badge/Reusable-Skill-111827?style=flat-square">
  19. <img alt="PavedPath Code" src="https://img.shields.io/badge/PavedPath-Code-7c3aed?style=flat-square">
  20. <img alt="GitHub CLI first" src="https://img.shields.io/badge/GitHub%20CLI-first-0969da?style=flat-square">
  21. <img alt="License MIT" src="https://img.shields.io/badge/license-MIT-green?style=flat-square">
  22. <img alt="Status public skill" src="https://img.shields.io/badge/status-public%20skill-blue?style=flat-square">
  23. </p>
  24. > **Status boundary / 状态边界**
  25. >
  26. > PavedPath Code is the code-focused edition of PavedPath. It helps agents solve software engineering problems by finding proven implementation paths from GitHub repositories, issues, pull requests, discussions, code examples, release notes, and open-source evidence.
  27. >
  28. > PavedPath Code(代码版)用于解决代码、工程、依赖、构建、部署、集成、API 使用等问题。它不是泛泛搜索 GitHub,而是从开源项目、issue、PR、示例、release notes 等证据中找到已经被验证过的实现路径,再转译成本地可执行方案。
  29. >
  30. > This repository is not the future general-purpose PavedPath. Non-code life decisions, self-media workflows, study methods, consumer decisions, and broad research tasks are out of scope here.
  31. ## 复制给智能体安装
  32. 把下面这段话复制到 Codex、Claude Code、Cursor Agent、ChatGPT Agent 或其他支持读取 GitHub 项目的智能体:
  33. ```text
  34. 请使用 https://github.com/Jia-Ethan/pavedpath-code 帮我安装或接入 PavedPath Code(代码版)这个通用 Skill。先阅读 README、SKILL.md、MIGRATION.md 和 references/,确认它的边界是代码 / 工程问题:bug、runtime error、build / test / deploy failure、dependency issue、framework/API usage、integration blocker、implementation pattern、工程工具/库选型,以及开源方案本地适配。不要把它扩展成生活、消费、自媒体或学习方法的通用 PavedPath。安装前先审计将写入的准确路径;如果你的环境有 skills 目录,就安装到对应的 active skill 目录并避免同时保留旧的 github-solution-research/SKILL.md;如果没有固定 skill 目录,就把 README 和 SKILL.md 转成你的本地可复用指令。写入前展示计划和备份路径,等我确认;确认后再备份、安装,并用一次最小调用验证新名称 pavedpath-code / PavedPath Code 可被正确识别。不要保存 token、cookie、私有仓库内容、敏感日志或凭证。
  35. ```
  36. ## 友链 / Community
  37. 本项目接受 LINUX DO 社区佬友监督与反馈:[LINUX DO](https://linux.do/)
  38. ## 简体中文
  39. ### 项目定位
  40. PavedPath Code(代码版)帮助 Agent 避免为代码问题重复造轮子。它先定义本地工程问题,再用 GitHub 和开源证据寻找已经被走通的路径:成熟项目、issue、PR、discussion、代码、示例、release notes 和官方项目文档。最后,它把最强证据转译为本地最小适配、验证命令和风险边界。
  41. 它不是“搜索 GitHub 链接”的工具。GitHub 是主要证据源,目标是找到开源世界已经验证过的实现路径,并判断这条路径是否适合当前代码库。
  42. ### 适用范围
  43. 适合使用 PavedPath Code:
  44. - bug、runtime error、build/test/deploy failure;
  45. - dependency、SDK、framework、API usage 或 integration blocker;
  46. - 需要寻找实现模式、配置形态、测试夹具、迁移路径或工具/库选型;
  47. - 需要比较多个开源项目,并说明 Stars、license、活跃度、适配成本和风险;
  48. - 需要从 issue、PR、release notes、示例代码或测试中提取可落地的修复模式;
  49. - 需要回答“这个工程问题在开源世界是否已有可验证路径”。
  50. 不要用于:
  51. - 文案、小型本地重构、或代码库已经明确给出答案的改动;
  52. - 非代码问题、生活问题、自媒体工作流、学习方法、消费决策等未来通用版 PavedPath 才应覆盖的场景;
  53. - 用户明确禁止联网或 GitHub 研究的任务;
  54. - 未获授权的私有仓库、凭证、cookie、token、公司内部代码、敏感日志、production data 或不可公开上下文;
  55. - 生产事故尚未完成本地日志、运行状态和官方文档核对时,用开源搜索替代现场排障。
  56. ### Features
  57. | 能力 | 已包含内容 | 边界 |
  58. | --- | --- | --- |
  59. | GitHub CLI first | 默认使用 `gh search repos`、`gh search issues`、`gh search prs`、`gh search code`、`gh repo view`、`gh pr view`、`gh issue view` 和 `gh api` | 不依赖仓库内置搜索脚本;`gh` 结果仍需深读和本地验证 |
  60. | 问题证据搜索 | 围绕错误文本、包名、API 名、版本号、配置键、框架和失败命令搜索 issues、PRs、code、examples、release notes | 只把 GitHub 当证据来源,不把链接数量或 Stars 当成结论 |
  61. | 仓库候选研究 | 按问题匹配、Stars、license、活跃度、示例质量和适配成本比较公开仓库 | Stars 是成熟度信号,不会覆盖 maintainer evidence、merged PR、official examples 或可复现代码 |
  62. | 条件子代理研究 | 当问题跨多个生态、查询族或证据面时,可拆给子代理并行只读研究 | 子代理不是默认强制;controller 仍负责范围控制、去重、排序、本地适配和最终验证 |
  63. | 输出证据闭环 | `SKILL.md` 要求记录 search path、subagent used/skipped、key evidence、rejected options、verification standard | 使用子代理时必须留下 subagent trace,避免“搜了很多”但没有可复核证据 |
  64. | 智能体集成 | `SKILL.md` 和 `agents/openai.yaml` 提供可复用 Skill 指令、展示信息和默认 prompt | 可安装到 Codex、Claude Code、Cursor Agent 或其他支持本地指令/Skill 的智能体环境 |
  65. ### 工作流
  66. ```mermaid
  67. flowchart LR
  68. A["Local software engineering problem"] --> B["Frame symptom, versions, constraints"]
  69. B --> C["Search GitHub and open-source evidence"]
  70. C --> D["Rank evidence and repositories"]
  71. D --> E["Deep-read strongest matches"]
  72. E --> F["Extract proven path and risks"]
  73. F --> G["Map to local adaptation"]
  74. G --> H["Verify with tests, builds, requests, or logs"]
  75. ```
  76. 默认研究路径:
  77. 1. 先在本地定义问题:目标、症状、错误文本、版本、运行环境、约束和已尝试方案。
  78. 2. 选择证据面:错误和回归优先搜 issue/PR/release/code;能力选型优先搜仓库候选;实现卡点两者都用。
  79. 3. 判断是否需要子代理。只有当任务跨多个独立生态、查询族或证据面时才拆分;否则说明跳过原因。
  80. 4. 用 `gh` 和精确查询搜索公开 GitHub:错误文本、包名、API 名、版本号、配置键、框架和失败命令。
  81. 5. 按问题匹配度、证据强度、本地适用性、可操作性和项目成熟度排序。
  82. 6. 深读最强候选,提取可复用接口、配置、测试、工作流、风险和 license 边界。
  83. 7. 合并、去重并拒绝不适配候选;使用子代理时由 controller 直接核验关键 claim。
  84. 8. 输出本地修复或实施建议,并用测试、构建、真实请求、日志或人工检查完成验证标准。
  85. ### Installation
  86. 安装到你的智能体 active skill / instructions 目录。下面示例使用 `~/.codex/skills`;Claude Code、Cursor Agent、ChatGPT Agent 或其他智能体请按自己的本地指令目录改写路径:
  87. ```bash
  88. mkdir -p ~/.codex/skills
  89. git clone https://github.com/Jia-Ethan/pavedpath-code.git \
  90. ~/.codex/skills/pavedpath-code
  91. ```
  92. 更新已有安装:
  93. ```bash
  94. git -C ~/.codex/skills/pavedpath-code pull --ff-only
  95. ```
  96. 建议按需安装并登录 GitHub CLI:
  97. ```bash
  98. gh auth status
  99. ```
  100. 这个 Skill 不绑定任何具体模型或智能体。它吸收了多 agent 搜索建议,但保持平台无关;真正的约束在于问题拆分、证据链接、去重、controller 复核和本地验证。
  101. ### Usage examples
  102. 在智能体中调用 Skill:
  103. ```text
  104. Use $pavedpath-code to investigate this Vite build error.
  105. Find matching GitHub issues, merged PRs, release notes, and reusable fixes,
  106. then recommend the smallest local adaptation and verification command.
  107. ```
  108. 搜索仓库候选:
  109. ```bash
  110. gh search repos "browser automation agent" \
  111. --archived=false \
  112. --sort stars \
  113. --order desc \
  114. --limit 10 \
  115. --json fullName,url,description,stargazersCount,forksCount,language,license,pushedAt,isArchived,openIssuesCount
  116. ```
  117. 搜索某个仓库内的 issue:
  118. ```bash
  119. gh search issues '"Cannot find module" "Node.js 22"' \
  120. --repo owner/repo \
  121. --sort updated \
  122. --order desc \
  123. --limit 10 \
  124. --json title,url,state,updatedAt,commentsCount,repository,body
  125. ```
  126. 搜索 merged PR:
  127. ```bash
  128. gh search prs '"ERR_PACKAGE_PATH_NOT_EXPORTED" vite plugin' \
  129. --repo owner/repo \
  130. --merged \
  131. --sort updated \
  132. --order desc \
  133. --limit 10 \
  134. --json title,url,state,updatedAt,commentsCount,repository,body
  135. ```
  136. 查看仓库基本信息:
  137. ```bash
  138. gh repo view owner/repo \
  139. --json nameWithOwner,url,description,stargazerCount,forkCount,licenseInfo,primaryLanguage,pushedAt,repositoryTopics,homepageUrl
  140. ```
  141. ### Output contract
  142. 当 PavedPath Code 实质影响结论时,回答应包含:
  143. - 本地问题画像:目标、症状、版本、环境和约束。
  144. - 搜索路径:查询词、搜索面、候选来源,以及是否使用或跳过子代理。
  145. - 子代理 trace:仅在使用子代理时输出,包含 scope、evidence surfaces、key findings、rejected candidates、deduplication results、controller verified claims。
  146. - 候选项目:repo、Stars、forks、语言、license、活跃度、基本内容、匹配理由和适配成本。
  147. - 关键证据:issue、PR、代码、示例、release notes 或文档链接,以及为什么匹配。
  148. - 推荐方案:直接复用什么、本地适配什么、避免复制什么。
  149. - 风险和拒绝项:旧版本、不适配、license、隐私、安全或部署风险。
  150. - 验证标准:测试、构建、复现命令、真实请求或人工检查。
  151. - 置信度:证据弱或没有强匹配时必须明确说明。
  152. ### Security
  153. - 默认只研究公开 GitHub 内容。私有仓库必须由用户明确授权并限定范围。
  154. - 不要把 GitHub token、cookie、密码、API key、私有仓库内容、内部上下文、敏感日志、production data 或凭证写入 prompt、输出、日志、README、脚本或记忆文件。
  155. - 不要把 token、cookie、私有仓库内容、敏感日志、secrets、production data 或凭证交给子代理。
  156. - 只有在 `gh` 命令明确出现 403、429、私有仓库授权错误或未登录提示时,才需要检查 `gh auth status`。
  157. - 避免复制大段第三方代码。优先复用公开 API、配置形态、工作流、测试模式和架构思路;如需代码复用,先检查 license 和归属要求。
  158. - 对安全、支付、鉴权、基础设施或生产运维类问题,GitHub 证据必须与当前官方文档或官方仓库交叉验证。
  159. ### Roadmap
  160. 当前已包含:
  161. - Skill 主入口:`SKILL.md`
  162. - OpenAI agent metadata:`agents/openai.yaml`
  163. - 研究评分和提取参考:`references/`
  164. - GitHub CLI first 的查询模板和输出契约
  165. - 条件式 subagent / parallel research guidance
  166. 可改进方向:
  167. - 增加更结构化的 JSON schema 输出。
  168. - 增加针对常见语言生态的查询模板。
  169. - 增加离线示例夹具,方便在不访问 GitHub API 时演示输出格式。
  170. - 增加 CI,检查 Markdown 链接、格式和敏感信息模式。
  171. 不会承诺:
  172. - 自动修复本地代码。
  173. - 自动判断所有 GitHub 结果真假。
  174. - 保证每个工程问题都有公开答案。
  175. - 在未授权范围内读取或复制私有代码。
  176. ## English
  177. ### Project positioning
  178. PavedPath Code is the code-focused edition of PavedPath. It helps agents avoid reinventing solutions for software engineering problems by finding proven implementation paths from GitHub repositories, issues, pull requests, discussions, code examples, release notes, and open-source evidence.
  179. It is not a generic GitHub link search. GitHub is the primary evidence source; the goal is to find a path the open-source world has already walked, decide whether it fits the local codebase, and adapt the strongest pattern with minimal, verifiable changes.
  180. This repository is intentionally scoped to code and engineering work. The future general-purpose PavedPath is out of scope.
  181. ### Scope
  182. Use PavedPath Code for:
  183. - bugs, runtime errors, build/test/deploy failures;
  184. - dependency, SDK, framework, API usage, or integration blockers;
  185. - implementation patterns, configuration shapes, test fixtures, migration paths, or engineering tool/library selection;
  186. - comparing open-source projects by Stars, license, activity, fit, adaptation cost, and risk;
  187. - extracting actionable fixes from issues, PRs, release notes, examples, or tests;
  188. - answering whether a concrete engineering problem already has a proven open-source path.
  189. Do not use it for:
  190. - copy edits, tiny local refactors, or changes where the existing codebase already dictates the answer;
  191. - non-code life decisions, self-media workflows, study methods, consumer decisions, or broad general research;
  192. - tasks where the user explicitly forbids network or GitHub research;
  193. - unauthorized private repositories, credentials, cookies, tokens, internal company code, sensitive logs, production data, or non-public context;
  194. - production incidents where local logs, runtime state, and official docs have not been checked first.
  195. ### How it works
  196. Default research path:
  197. 1. Frame the local problem: goal, symptom, error text, versions, runtime, constraints, and attempted fixes.
  198. 2. Choose the evidence surface: issues, PRs, releases, and code for errors; repository candidates for reusable capabilities; both for implementation blockers.
  199. 3. Decide whether subagents are useful. Use them only when the task spans independent ecosystems, query families, or evidence surfaces; otherwise state why they were skipped.
  200. 4. Search public GitHub with `gh` and targeted queries: exact errors, package names, API names, versions, config keys, frameworks, and failing commands.
  201. 5. Rank by problem fit, evidence strength, local applicability, actionability, and project maturity.
  202. 6. Deep-read the strongest candidates and extract reusable interfaces, configuration, tests, workflows, risks, and license boundaries.
  203. 7. Merge, deduplicate, and reject weak candidates; when subagents were used, the controller directly verifies the strongest claims.
  204. 8. Produce a local fix or implementation recommendation with a concrete verification command, request, test, log, or manual check.
  205. ### Installation
  206. Install into your agent runtime's active local skills/instructions directory. The example below uses `~/.codex/skills`; adapt the path for Claude Code, Cursor Agent, ChatGPT Agent, or another agent runtime:
  207. ```bash
  208. mkdir -p ~/.codex/skills
  209. git clone https://github.com/Jia-Ethan/pavedpath-code.git \
  210. ~/.codex/skills/pavedpath-code
  211. ```
  212. Update an existing installation:
  213. ```bash
  214. git -C ~/.codex/skills/pavedpath-code pull --ff-only
  215. ```
  216. Install and authenticate GitHub CLI when needed:
  217. ```bash
  218. gh auth status
  219. ```
  220. ### Usage examples
  221. Invoke the Skill in an agent:
  222. ```text
  223. Use $pavedpath-code to investigate this Vite build error.
  224. Find matching GitHub issues, merged PRs, release notes, and reusable fixes,
  225. then recommend the smallest local adaptation and verification command.
  226. ```
  227. Search repository candidates:
  228. ```bash
  229. gh search repos "browser automation agent" \
  230. --archived=false \
  231. --sort stars \
  232. --order desc \
  233. --limit 10 \
  234. --json fullName,url,description,stargazersCount,forksCount,language,license,pushedAt,isArchived,openIssuesCount
  235. ```
  236. Search matching issues in one repository:
  237. ```bash
  238. gh search issues '"Cannot find module" "Node.js 22"' \
  239. --repo owner/repo \
  240. --sort updated \
  241. --order desc \
  242. --limit 10 \
  243. --json title,url,state,updatedAt,commentsCount,repository,body
  244. ```
  245. Inspect repository basics:
  246. ```bash
  247. gh repo view owner/repo \
  248. --json nameWithOwner,url,description,stargazerCount,forkCount,licenseInfo,primaryLanguage,pushedAt,repositoryTopics,homepageUrl
  249. ```
  250. ### Output contract
  251. When PavedPath Code materially affects an answer, the answer should include:
  252. - Local problem profile: goal, symptom, versions, environment, and constraints.
  253. - Search path: queries, GitHub/open-source surfaces, discovery methods used, and whether subagents were used or skipped.
  254. - Subagent trace: only when subagents were used; include scope, evidence surfaces, key findings, rejected candidates, deduplication results, and controller verified claims.
  255. - Repository candidates: repo, Stars, forks, language, license, activity, basic content, fit rationale, and adaptation cost.
  256. - Key evidence: links to issues, PRs, code, examples, release notes, or docs, with match rationale.
  257. - Recommended solution: what to reuse directly, what to adapt locally, and what to avoid copying.
  258. - Rejected or risky options: stale versions, mismatches, license, privacy, security, or deployment risks.
  259. - Verification standard: test, build, reproduction command, real request, log, or manual check.
  260. - Confidence label when evidence is weak or no strong open-source solution was found.
  261. ### Security
  262. - Research public GitHub content by default. Private repositories require explicit user authorization and a bounded scope.
  263. - Do not write GitHub tokens, cookies, passwords, API keys, private repository contents, internal context, sensitive logs, production data, or credentials into prompts, outputs, logs, README files, scripts, or memory files.
  264. - Do not pass tokens, cookies, private repository contents, sensitive logs, secrets, production data, or credentials to subagents.
  265. - Only check `gh auth status` after a `gh` command reports 403, 429, a private repository authorization error, or an explicit not-authenticated message.
  266. - Avoid copying large chunks of third-party code. Prefer public APIs, configuration shapes, workflows, test patterns, and architecture ideas; check license and attribution obligations before reusing code.
  267. - For security, payments, auth, infrastructure, or production operations, cross-check GitHub evidence against current official docs or official repositories.
  268. ## Migration
  269. `github-solution-research` has been renamed to **PavedPath Code**.
  270. Previous behavior is preserved; this is a naming and positioning update. New installations should use:
  271. ```bash
  272. git clone https://github.com/Jia-Ethan/pavedpath-code.git \
  273. ~/.codex/skills/pavedpath-code
  274. ```
  275. Do not keep an old `github-solution-research/SKILL.md` under an active skill root together with `pavedpath-code/SKILL.md`; an agent runtime may recursively load both.
  276. ## License
  277. MIT License. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.