openclaw - ✅(Solved) Fix gh-issues SKILL.md exceeds 500-line best practice (865 lines) [1 pull requests, 1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#50972Fetched 2026-04-08 01:06:05
View on GitHub
Comments
0
Participants
1
Timeline
3
Reactions
0
Participants
Timeline (top)
cross-referenced ×2referenced ×1

The gh-issues skill's SKILL.md is currently 865 lines, significantly exceeding the recommended 500-line limit from Anthropic's "Lessons from Building Claude Code" best practices.

Root Cause

  • Long SKILL.md files consume significant context window when loaded
  • AI attention distribution degrades with longer documents — key instructions near the end may be deprioritized
  • Other OpenClaw skills already follow the references/ + scripts/ separation pattern (e.g., 1password, himalaya, model-usage)

Fix Action

Fixed

PR fix notes

PR #51019: skill(gh-issues): split oversized references from SKILL.md

Description (problem / solution / changelog)

Summary

  • keep the gh-issues skill workflow in the main SKILL.md
  • move bulky reference-heavy prompt and review details into references/
  • reduce the main SKILL.md below the 500-line best-practice limit

Testing

  • wc -l skills/gh-issues/SKILL.md -> 483

Closes #50972

Changed files

  • skills/gh-issues/SKILL.md (modified, +12/-394)
  • skills/gh-issues/references/fix-subagent-prompt.md (added, +165/-0)
  • skills/gh-issues/references/reporting-and-watch.md (added, +63/-0)
  • skills/gh-issues/references/review-handler.md (added, +199/-0)
RAW_BUFFERClick to expand / collapse

Summary

The gh-issues skill's SKILL.md is currently 865 lines, significantly exceeding the recommended 500-line limit from Anthropic's "Lessons from Building Claude Code" best practices.

Why this matters

  • Long SKILL.md files consume significant context window when loaded
  • AI attention distribution degrades with longer documents — key instructions near the end may be deprioritized
  • Other OpenClaw skills already follow the references/ + scripts/ separation pattern (e.g., 1password, himalaya, model-usage)

Suggestion

Split phase definitions, flag tables, and detailed workflow descriptions into references/ sub-files, keeping SKILL.md under 500 lines with only the core procedure.

Measured skill sizes (top 6)

SkillLines
gh-issues865 ⚠️
xurl461
skill-creator372
coding-agent295
himalaya257
healthcheck245

Environment

  • OpenClaw 2026.3.13
  • Reference: Anthropic "Lessons from Building Claude Code: How We Use Skills" (2026-03-17)

extent analysis

Fix Plan

To address the issue, we will split the SKILL.md file into smaller sub-files within a references/ directory, following the pattern used by other OpenClaw skills.

Step-by-Step Solution:

  1. Create a references/ directory within the gh-issues skill directory.
  2. Move phase definitions to a new file, e.g., references/phases.md.
  3. Move flag tables to a new file, e.g., references/flags.md.
  4. Move detailed workflow descriptions to a new file, e.g., references/workflow.md.
  5. Update SKILL.md to include links to these new reference files and keep only the core procedure.

Example Code Snippet:

# SKILL.md (updated)
## Core Procedure
1. Initialize the issue tracker.
2. See [phases](references/phases.md) for detailed phase definitions.
3. Refer to [flags](references/flags.md) for available flag options.
4. Follow the [workflow](references/workflow.md) for step-by-step instructions.

Verification

After implementing these changes, verify that the SKILL.md file is under 500 lines and that the links to the reference files are working correctly.

Extra Tips

  • Regularly review and refactor large files to maintain readability and adhere to best practices.
  • Use clear and descriptive file names and directory structures to improve navigation and understanding of the codebase.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - ✅(Solved) Fix gh-issues SKILL.md exceeds 500-line best practice (865 lines) [1 pull requests, 1 participants]