Agent skill

file-issue

File a GitHub issue or local issue from the current conversation. Use when bugs, regressions, improvements, or design tasks are identified during a session and need to be captured as tracked work. Trigger when the user says "file an issue", "create an issue", "track this", "open a bug", "make a ticket", "note this down", "log this", or when a notable problem is discovered that should be recorded. Also use when you discover a code quality issue, notice a missing feature during code review, want to capture technical debt, or when the user says "we should track this", "that's a bug", or similar. Works with both GitHub-hosted projects (via gh CLI) and non-GitHub projects (appending to ISSUES.md).

View SKILL.md on GitHub Repository
Stars 0
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/lanmogu98/dev-skills/tree/main/file-issue

SKILL.md

File Issue

Capture bugs, improvements, or design tasks as tracked issues — either on GitHub or in a local ISSUES.md.

Detect Issue Destination

Before drafting, figure out where the project tracks issues. This matters because GitHub-hosted projects get labels, assignees, and PR auto-close for free, while non-GitHub projects need a local equivalent.

  1. Check if project is GitHub-hosted: git remote -v | grep github.com
  2. Check AGENTS.md ## Task Entry section for the canonical tracking method
  3. GitHub-hosted → file via gh issue create
  4. Non-GitHub → append to ISSUES.md at project root

Issue Templates

Read references/templates.md for the full template structures. Choose the template that best fits what was identified:

Template When to use Labels
task An improvement, refactor, or feature request agent-generated + priority
bug-report A bug or regression was found bug, agent-generated
design-note Complex work needing detailed implementation context agent-generated + priority

Workflow

1. Gather Context from Conversation

Extract:

  • What is broken or missing — concrete symptoms, error messages, failing test output
  • Where it happens — file paths, line numbers, module names
  • How to reproduce (for bugs) — steps, commands, or minimal config
  • Root cause (if known) — what investigation revealed
  • Severity — blocks work, causes data loss, or cosmetic?

If the conversation is ambiguous about what to file, ask the user to clarify before proceeding.

2. Classify the Issue

Pick the template (task, bug-report, or design-note) that best fits. If unsure, ask the user — getting the template right keeps issues scannable.

3. Duplicate Check

Before creating anything, check for existing issues on the same topic. Filing duplicates wastes everyone's time and fragments discussion.

GitHub-hosted:

bash
gh issue list --state open --search "<keyword>"

Non-GitHub: scan ISSUES.md for similar items.

If a matching issue exists, tell the user and offer to comment on it (GitHub) or update it (local) instead.

4. Draft the Issue

Title: Short imperative sentence, optionally prefixed with a scope tag (e.g., [auth] Fix session expiry). Under 80 characters.

Body: Use the section structure from the matching template in references/templates.md.

Keep the body concise — reference code with file:line links rather than pasting inline, include error messages in trimmed code blocks, and aim for under ~200 words. The issue should read as if the human wrote it, not the agent.

5. Confirm or File Directly

When the user explicitly asked to file an issue, go ahead and file it — they can review and edit on GitHub. When the agent surfaced the issue on its own (not explicitly requested), show the drafted title and body first and wait for approval. This avoids surprising the user with unexpected issues in their tracker.

6. File the Issue

GitHub-hosted:

bash
gh issue create \
  --title "<title>" \
  --label "agent-generated" \
  --body "$(cat <<'EOF'
<body>
EOF
)"

Add template-appropriate labels (bug for bug reports, priority p1/p2/p3 if known). If a label doesn't exist, skip it rather than creating new labels — label management is a human decision.

Non-GitHub: Append a new row to the ## Active table in ISSUES.md:

  • Generate next ID (increment from highest existing, e.g., T-003)
  • Set priority based on severity context
  • Status: Pending

If the issue needs detailed notes (design-note type), also add a section to docs/ISSUE_DETAILS.md.

7. Report Back

Print the issue URL (GitHub) or the ID and location (local) so the user can see it.

Writing Style

Issues are most useful when they're scannable. Every sentence should convey information the reader doesn't already have. Reference code with annotated links (file.py:42 — description), not narrative explanations. No preamble ("I noticed...", "During our conversation...").

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

lanmogu98/dev-skills

dev-workflow

Comprehensive engineering workflow for making code changes in existing codebases. Use this skill whenever the user wants to implement a feature, fix a bug, write or run tests, refactor code, create a pull request, do a code review, or make a commit. Also trigger when the user mentions branch strategy, TDD, test-driven development, pre-commit checks, merge conflicts, or debugging workflow. Covers the full cycle: exploration → design (tests first) → implementation → pre-commit → PR. Includes bug fix workflow, code review checklists, refactoring safety, multi-agent collaboration via worktrees, and optional domain review for projects with real-world consequences. If the user is working on an existing codebase and making changes of any kind, this skill applies.

0 0
Explore
lanmogu98/dev-skills

project-init

One-time project initialization protocol for setting up new repositories or organized project workspaces optimized for human-AI collaborative development. Use this skill whenever the user wants to start a new project, bootstrap a repo, scaffold work from a design doc, create AGENTS.md or CLAUDE.md context files, or set up a project for use with Cursor, Claude Code, or Codex. This applies to software, automation, documentation, configuration, research, and similar git-tracked projects. Also trigger when the user mentions "new repo", "project setup", "design doc to code", "create project structure", or asks about AI context files or cross-agent compatibility. This skill runs once to create the scaffold, then hands off to dev-workflow for ongoing development.

0 0
Explore
mattpocock/skills

handoff

Compact the current conversation into a handoff document for another agent to pick up.

111,310 9,758
Explore
mattpocock/skills

scaffold-exercises

Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.

111,310 9,758
Explore
mattpocock/skills

setup-pre-commit

Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.

111,310 9,758
Explore
mattpocock/skills

edit-article

Edit and improve articles by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, or improve an article draft.

111,310 9,758
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results