Agent skill

Fix GitHub Issue

by open-guji in open-guji/luatex-cn

“修复 GitHub Issue 的完整工作流”

— description from SKILL.md by open-guji
Apache-2.0Auto-check passedTesting & QA

Install Fix GitHub Issue

skills CLI
$ npx skills add open-guji/luatex-cn --skill fix-github-issue -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install open-guji/luatex-cn fix-github-issue --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/open-guji/luatex-cn.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/fix-github-issue .claude/skills/fix-github-issue && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
fix-github-issue
GitHub stars
118
Token cost
~2k tokens
SKILL.md length
382 words
Files
1
Skills in repo
7
Repo updated
First seen
Licence
Apache-2.0

At a glance

  • Works in 12 steps: 获取 Issue 详情 → 定位相关代码 → 理解代码逻辑 → …
  • SKILL.md covers 1. 获取 Issue 详情, 2. 定位相关代码, 3. 理解代码逻辑 and 4. 重现问题, plus 9 more sections
  • Calls python3, git and gh

About this skill

Fix GitHub Issue is a skill in open-guji/luatex-cn (118 stars). Its SKILL.md is about 2k tokens. Licence: Apache-2.0.

Workflow steps

12 steps, taken from the step headings in SKILL.md.

  1. 获取 Issue 详情
  2. 定位相关代码
  3. 理解代码逻辑
  4. 重现问题
  5. 实现修复
  6. 验证修复(关键!)
  7. 创建 past-issue 回归测试(必须!)
  8. 更新基线
  9. 提交代码
  10. 最终验证
  11. 推送代码
  12. 在 Issue 中添加修复总结

What it can do on your machine

Read from SKILL.md and the folder at commit 8c48bdc. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • python3
    • git
    • gh

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use git and gh, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Fix GitHub Issue loads about 2k tokens when it runs. Until then it costs about 10 tokens; SKILL.md has 382 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~10
When it runs · the whole SKILL.md, loaded when a task matches
~2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from open-guji/luatex-cn at commit 8c48bdc, republished under its Apache-2.0 licence (© open-guji). 382 words, ~2,035 tokens.

Download SKILL.mdSave it as .claude/skills/fix-github-issue/SKILL.md (or your agent's skills folder).
name
fix-github-issue
description
修复 GitHub Issue 的完整工作流

修复 GitHub Issue 工作流

当需要修复 GitHub issue 时,请遵循以下完整流程以确保代码质量和正确性。

1. 获取 Issue 详情

// turbo 首先,使用 gh CLI 工具获取 issue 的完整信息:

bash
gh issue view <issue-number> --repo open-guji/luatex-cn

目的:

  • 理解问题的具体描述
  • 查看附带的截图或示例
  • 了解用户期望的行为

2. 定位相关代码

使用搜索工具找到相关的代码文件:

// turbo 按关键词搜索(中英文关键词):

bash
# 使用 Grep 工具搜索 issue 中提到的关键词
# 支持中英文混合搜索

// turbo 按文件类型搜索:

bash
# 使用 Glob 工具查找相关文件
# 例如:**/*.lua, **/*.sty, **/*.tex

关键文件结构:

  • tex/core/ - 核心渲染逻辑
  • tex/guji/ - 古籍特定功能
  • tex/banxin/ - 版心相关功能
  • tex/decorate/ - 装饰元素
  • test/regression_test/tex/ - 测试文件

3. 理解代码逻辑

// turbo 阅读相关文件:

  • 使用 Read 工具仔细阅读定位到的文件
  • 理解渲染流程和数据流
  • 找出问题的根本原因

系统架构:

  1. Stage 1: Flatten nodes(展平节点)
  2. Stage 2: Layout grid(布局计算)
  3. Stage 3: Render page(渲染应用)
    • 绘制背景
    • 绘制边框和装饰元素
    • 应用节点坐标
    • 插件渲染

关键概念:

  • Z-order(层叠顺序):后渲染的元素显示在上层
  • Node list order:节点在列表中的顺序决定渲染顺序
  • Plugin system:功能通过插件系统集成
  • 坐标系统:理解 xoffset/yoffset 和 kern/shift 的区别

4. 重现问题

关键步骤:在修复前,必须先成功重现问题。

4.1 在 test_example 中重现

使用 /home/lishaodong/workspace/luatex-cn/test_example 目录创建最小复现用例:

bash
cd /home/lishaodong/workspace/luatex-cn/test_example
# 创建测试文件 issue_<number>.tex
cat > issue_<number>.tex << 'EOF'
\documentclass{ltc-guji}  % 或 ltc-cn-vbook 等
% 根据 issue 描述添加相关配置
\begin{document}
% 最小化的测试内容
\end{document}
EOF

# 编译测试
lualatex -interaction=nonstopmode issue_<number>.tex

目的:

  • 验证问题确实存在
  • 理解问题的触发条件
  • 创建简化的复现场景
4.2 决定测试用例位置

成功重现后,根据用法频率选择测试位置:

常见用法 → test/regression_test/basic/tex/

如果是常用功能或核心特性,在已有测试文件中添加测试用例:

bash
# 例如:标点相关 → punctuation.tex
# 例如:夹注相关 → jiazhu.tex
# 例如:版心相关 → page.tex

特点:

  • 会被频繁运行(每次 regression test)
  • 应该保持文件小而快
  • 覆盖该功能的多种使用场景
不常见用法 → test/regression_test/past_issue/tex/

如果是边缘场景或特定字体/配置,创建独立测试文件:

bash
# 命名格式:<feature>_issue<number>.tex
# 例如:vert_font_kinsoku_issue71.tex

特点:

  • 记录历史问题(防止回归)
  • 可以包含特殊配置或依赖
  • 文件名直接关联 issue 编号

判断标准:

条件位置
使用通用字体(Source Han Serif SC/TW-Kai)basic
使用特殊字体(KingHwa_OldSong + vert)past_issue
核心功能的常见用法(句读、夹注、版心)basic
特殊组合或边缘场景past_issue
简单示例(< 30 行)basic(合并到已有文件)
复杂示例(> 30 行)past_issue(独立文件)
4.3 创建测试用例

在 basic 中添加(合并到已有文件):

latex
% 在 test/regression_test/basic/tex/punctuation.tex 中添加
\newpage
% Test for issue #71: PUA punctuation positioning
\setmainfont[RawFeature={vert}]{KingHwa_OldSong}
测试标点位置,。、

在 past_issue 中创建(独立文件):

bash
cd test/regression_test/past_issue/tex
cat > vert_font_kinsoku_issue71.tex << 'EOF'
\documentclass{ltc-cn-vbook}
\setmainfont[RawFeature={vert}]{KingHwa_OldSong}
\begin{document}
\begin{正文}
% 从 test_example 复制已验证的最小复现用例
\end{正文}
\end{document}
EOF

5. 实现修复

修改代码时注意:

  • 保持代码风格一致
  • 添加清晰的注释说明修改意图
  • 考虑性能影响
  • 避免破坏现有功能

常见问题类型及修复思路:

  • 渲染层级问题:调整节点插入位置或渲染顺序
  • 位置计算问题:检查坐标计算逻辑和参数传递
  • 视觉效果问题:确认渲染参数和颜色设置
  • 布局问题:检查网格计算和列宽行高设置

6. 验证修复(关键!)

期望:修复后,regression test 应该在相关测试文件上显示变化。

6.1 编译测试

// turbo 找到或创建相关的测试文件并编译:

bash
lualatex --interaction=nonstopmode test/regression_test/basic/tex/<test-file>.tex
# 或
lualatex --interaction=nonstopmode test/regression_test/past_issue/tex/<test-file>.tex
6.2 单元测试(如果修改了 Lua 代码)

// turbo

bash
texlua test/run_all.lua

必须先通过 unit tests,再运行 regression tests。

6.3 回归测试

// turbo 运行完整的回归测试以确保没有破坏现有功能:

bash
python3 test/regression_test.py check

关键验证点:

  1. ✅ 修复的测试文件应该显示差异(FAIL 或像素差异)

    • 如果 regression test 显示所有测试都 PASSED(0 像素差异)
    • 说明修复可能没有生效或测试用例不正确
  2. ✅ 其他测试文件应该保持通过(PASSED,0 像素差异)

    • 如果其他文件也出现差异,说明修复影响了其他功能
    • 需要检查是否引入了副作用

期望输出示例:

FAIL: vert_font_kinsoku_issue71.tex differs on pages: [1]  ← 修复生效!
PASSED: punctuation.tex (0 pixels diff)                    ← 其他测试不受影响
PASSED: jiazhu.tex (0 pixels diff)
...
6.4 视觉验证

检查修复效果:

bash
# 查看生成的 PDF
okular test/regression_test/basic/pdf/<test-file>.pdf
# 或
okular test/regression_test/past_issue/pdf/<test-file>.pdf

# 查看差异图像
ls -lh test/regression_test/basic/diff/
# 或
ls -lh test/regression_test/past_issue/diff/

确认要点:

  • ✅ 生成的 PDF 中问题已修复
  • ✅ 视觉效果符合 issue 描述的预期
  • ✅ 没有引入新的视觉问题
  • ✅ 如果修复涉及多个测试文件,确保都检查过

使用 overlay_compare.py 对比修复前后(可选):

bash
python3 scripts/overlay_compare.py \
  test/regression_test/past_issue/baseline/<test>-1.png \
  test/regression_test/past_issue/current/<test>-1.png \
  /tmp/overlay.png

# 查看叠加对比图
okular /tmp/overlay.png

7. 创建 past-issue 回归测试(必须!)

每个 issue 修复必须在 test/regression_test/past_issue/tex/ 中创建对应的回归测试文件,防止问题复发。

Show full SKILL.md (158 more words)Show less
7.1 创建测试文件
bash
# 命名格式:<feature>_issue<number>.tex
cat > test/regression_test/past_issue/tex/<feature>_issue<number>.tex << 'EOF'
% Issue #<number>: <问题简要描述>
% https://github.com/open-guji/luatex-cn/issues/<number>
%
% 修复前: <修复前的错误行为>
% 修复后: <修复后的正确行为>
\documentclass{ltc-guji}
\setmainfont{TW-Kai}
\关闭分页
\无标点模式

\title{测试}
\chapter{Issue <number>}

\begin{document}
\begin{正文}
% 从 test_example 复制已验证的最小复现用例
% 包含多个测试场景(正常用法 + 边缘情况)
\end{正文}
\end{document}
EOF

测试文件要求:

  • 文件头注释包含 issue 编号、GitHub URL、修复前后行为描述
  • 包含正常对照(不受影响的基线场景)
  • 包含核心复现场景(触发 bug 的用例)
  • 可选:包含边缘情况(auto-balance 切换、不同 textbox 类型等)
7.2 生成 baseline
bash
# 生成 past_issue suite 的 baseline
python3 test/regression_test.py save --past-issues
7.3 验证测试通过
bash
# 确认新测试能通过
python3 test/regression_test.py check --past-issues

8. 更新基线

仅当修复导致了预期的视觉变化时更新基线:

// turbo

bash
# 更新所有有差异的测试文件
python3 test/regression_test.py save

# 或只更新特定测试文件
python3 test/regression_test.py save test/regression_test/past_issue/tex/<test-file>.tex

注意事项:

  • ✅ 只保存真正需要更新的基线图像
  • ✅ 确认所有视觉变化都是预期且正确的
  • ❌ 不要提交临时文件(diff/ 和 current/ 目录)
  • ❌ 不要提交 PDF 文件(会自动生成)

验证更新:

bash
# 再次运行 regression test,应该全部 PASSED
python3 test/regression_test.py check

9. 提交代码

9.1 检查变更

// turbo

bash
git status
git diff

预期应该看到:

  • ✅ 修改的源代码文件(.lua, .sty, .tex)
  • ✅ 新增或更新的 baseline 图片(.png)
  • ✅ 新增的测试文件(如果在 past_issue 中创建了新测试)
  • ❌ 不应该有 PDF、辅助文件、diff/current 目录下的文件
9.2 暂存文件

只暂存需要提交的文件:

bash
git add <modified-source-files>  # .lua, .sty 等
git add test/regression_test/basic/baseline/*.png         # 如果更新了 basic 基线
git add test/regression_test/past_issue/baseline/*.png    # 如果更新了 past_issue 基线
git add test/regression_test/past_issue/tex/<new-test>.tex  # 如果创建了新测试

常见错误(不要提交):

  • ❌ test/regression_test/*/pdf/*.pdf - PDF 文件(自动生成)
  • ❌ test/regression_test/*/diff/*.png - 差异图(临时文件)
  • ❌ test/regression_test/*/current/*.png - 当前输出(临时文件)
  • ❌ *.aux, *.log, *.out - LaTeX 辅助文件
  • ❌ test_example/ 下的任何文件(仅用于本地测试)
9.3 编写提交信息

使用规范的提交信息格式。标题必须包含 fix #<number>(不是 (#number)),这样 GitHub Actions 才能自动关联 issue:

bash
git commit -m "fix #<issue-number>: <简短标题>

<详细描述原问题是什么,为什么会出现>

Changes:
- <具体改动点1>
- <具体改动点2>

<如有必要,说明技术实现细节>

Co-Authored-By: Claude <model> <noreply@anthropic.com>
"

提交信息要素:

  1. 标题:以 fix #<number>: 开头(不要 用 (#number) — GitHub 不会识别)
  2. 问题描述:说明原来的问题及其原因
  3. Changes:列出具体的代码改动
  4. 技术细节:如有必要,解释实现方案和考虑因素
  5. Co-Authored-By:标注协作者

10. 最终验证

// turbo 提交后再次运行回归测试确保一切正常:

bash
python3 test/regression_test.py check

所有测试应该显示 PASSED(基线已更新,不应再有差异)

11. 推送代码

bash
# 推送到远程 dev 分支
git push origin dev

12. 在 Issue 中添加修复总结

推送成功后,在 issue 中添加修复总结 comment。

流程:

  1. 先将 comment 内容展示给用户 review
  2. 用户确认后,使用 gh issue comment 命令发布:
bash
gh issue comment <issue-number> --repo open-guji/luatex-cn --body "$(cat <<'COMMENT'
✅ 修复已推送到 dev 分支。

## 问题总结
<简要说明问题是什么>

## 根本原因
<解释为什么会出现这个问题>

## 解决方案
<说明如何修复的>

## 测试验证
- ✓ unit tests 通过
- ✓ regression tests 通过
- ✓ 新增/更新测试: <test-file-name>

## 相关提交
- <commit-hash>: <commit-title>
COMMENT
)"

重要:

  • 不要手动关闭 issue — GitHub Actions 会自动标记为 fix ready,发布新版本时统一关闭
  • comment 内容必须先给用户 review — 确认后再发布

最佳实践

  1. 小步提交:一次只修复一个问题,避免混杂多个改动
  2. 充分测试:确保回归测试全部通过,验证视觉效果
  3. 详细文档:提交信息要清晰完整,便于代码审查和后续维护
  4. 保持沟通:不确定时在 issue 中与维护者讨论方案
  5. 代码审查:推送前自己先仔细审查所有改动
  6. 理解原理:深入理解代码逻辑,避免临时性的 hack 方案
  7. 考虑兼容性:确保修复不会影响其他功能或破坏向后兼容性

© open-guji, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .claude/skills/fix-github-issue of open-guji/luatex-cn.

Open the folder on GitHubat commit 8c48bdc

Compare with similar skills

Fix GitHub Issue next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Fix GitHub Issue compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Fix GitHub Issue this skillopen-guji/luatex-cn118—~2kAutomated safety check: PassApache-2.0
Lov Any2pdflovstudio/any2pdf211—~2.4kAutomated safety check: NotesMIT
Opendocsioteverythin/OpenDocs233—~746Automated safety check: NotesMIT
Using Streamlit Markdowniusztinpaul/designing-real-world-ai-agents-workshop513—~1.8kAutomated safety check: PassApache-2.0
Thu ThesisLeoYeAI/openclaw-master-skills2.2k—~4kAutomated safety check: PassMIT
Editor Updateqwrtln/Homm3BG-mission-book110—~1.2kAutomated safety check: PassCustom licence

Similar skills

  • Lov Any2pdf

    lovstudio/any2pdf

    Convert Markdown documents to professionally typeset PDF files with reportlab.

    211 GitHub stars~2.4k tokensUpdated 1 mo ago
    Documents & OfficeAuto-check: notes
  • Opendocs

    ioteverythin/OpenDocs

    Generates multi-format documentation (Word, PDF, PPTX, Markdown blog post, JIRA ticket, FAQ, changelog, LaTeX, social snippet, architecture diagram) from a GitHub README, npm package, local Markdown…

    233 GitHub stars~746 tokensUpdated 1 mo ago
    Documents & OfficeAuto-check: notes
  • Using Streamlit Markdown

    iusztinpaul/designing-real-world-ai-agents-workshop

    Covers all Markdown features in Streamlit including GitHub-flavored syntax plus Streamlit extensions like colored text, badges, Material icons, and LaTeX.

    513 GitHub stars~1.8k tokensUpdated 4 mo ago
    Documents & OfficeAuto-check passed
  • Thu Thesis

    LeoYeAI/openclaw-master-skills

    清华大学毕业论文 Word → PDF 一键格式规范化工具。输入任意 Word (.docx) 格式的清华毕业论文,自动转换为符合清华 thuthesis 官方 LaTeX 模板规范的高质量 PDF。适用于所有清华学位论文(MBA/学硕/专硕),一条命令搞定。功能:自动提取章节结构、中英文摘要、参考文献(自动生成 BibTeX)、图片(含…

    2.2k GitHub stars~4k tokensUpdated 2 mo ago
    Documents & OfficeAuto-check passed
  • Editor Update

    qwrtln/Homm3BG-mission-book

    Build a feature or fix a bug in the browser scenario builder under web/ — app, shared parsers, compile/PDF preview, GitHub pull-request flow, picker, search, routes — with tests and every…

    110 GitHub stars~1.2k tokensUpdated yesterday
    Documents & OfficeAuto-check passed
  • Release Latex Fork

    zly2006/zhihu-plus-plus

    Release the LaTeX fork used by Zhihu++. An agent skill from zly2006/zhihu-plus-plus.

    4.2k GitHub stars~1.8k tokensUpdated yesterday
    Documents & OfficeAuto-check passed

More from open-guji/luatex-cn

  • Compare Layouts

    open-guji/luatex-cn

    比较 Original (ltc-guji.cls) 和 Digital (ltc-guji-digital.cls) TeX 文件的 layout 输出

    118 GitHub stars~550 tokensUpdated 6 days ago
    Auto-check passed
  • Convert To Digital

    open-guji/luatex-cn

    将 ltc-guji.cls 文件转换为 ltc-guji-digital 格式. An agent skill from open-guji/luatex-cn.

    118 GitHub stars~747 tokensUpdated 6 days ago
    Auto-check passed
  • Prepare Next Version

    open-guji/luatex-cn

    准备下一个补丁版本 (Prepare next patch version release). An agent skill from open-guji/luatex-cn.

    118 GitHub stars~412 tokensUpdated 6 days ago
    Auto-check passed
  • Regression Test

    open-guji/luatex-cn

    运行视觉回归测试验证代码更改是否正确,支持 basic/pastissue/complete 套件及基线更新. An agent skill from open-guji/luatex-cn.

    118 GitHub stars~350 tokensUpdated 6 days ago
    Auto-check passed
  • Test Tex

    open-guji/luatex-cn

    通过回归测试框架编译并查看 TeX 文件的渲染效果,避免在工作目录生成多余 PDF. An agent skill from open-guji/luatex-cn.

    118 GitHub stars~278 tokensUpdated 6 days ago
    Auto-check passed
  • Refactor

    open-guji/luatex-cn

    清理重构代码 (Code cleanup and refactoring)

    118 GitHub stars~532 tokensUpdated 6 days ago
    Auto-check passed

Works with

Questions about Fix GitHub Issue

How do I install Fix GitHub Issue in Claude Code?

Run `npx skills add open-guji/luatex-cn --skill fix-github-issue -a claude-code`. Or copy the skill folder (.claude/skills/fix-github-issue in open-guji/luatex-cn) into .claude/skills/fix-github-issue in your project. Claude Code loads it when a task matches its description.

How do I install Fix GitHub Issue in Codex?

Run `npx skills add open-guji/luatex-cn --skill fix-github-issue -a codex`. Or copy the skill folder (.claude/skills/fix-github-issue in open-guji/luatex-cn) into .agents/skills/fix-github-issue in your project. Codex loads it when a task matches its description.

Can I use Fix GitHub Issue in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add open-guji/luatex-cn --skill fix-github-issue -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/fix-github-issue, .gemini/skills/fix-github-issue, .github/skills/fix-github-issue and .opencode/skills/fix-github-issue in your project.

What does Fix GitHub Issue need to run?

Going by SKILL.md and its folder, Fix GitHub Issue needs the command-line tools its instructions call (python3, git and gh).

Does Fix GitHub Issue access the network?

SKILL.md contains no URLs. Its commands use git and gh, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Fix GitHub Issue safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Fix GitHub Issue use?

Fix GitHub Issue is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Fix GitHub Issue use?

About 2k tokens (SKILL.md is roughly 8.1k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Fix GitHub Issue?

Skills that share tags, products or a category with Fix GitHub Issue: Lov Any2pdf (lovstudio/any2pdf, 211 stars), Opendocs (ioteverythin/OpenDocs, 233 stars), Using Streamlit Markdown (iusztinpaul/designing-real-world-ai-agents-workshop, 513 stars) and Thu Thesis (LeoYeAI/openclaw-master-skills, 2.2k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Fix GitHub Issue?

open-guji (a GitHub organization) maintains it in open-guji/luatex-cn, which has 118 GitHub stars. The repository holds 7 skills in this directory. The repository was last updated on October 2, 2026.

Source: open-guji/luatex-cn on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.