> ## Documentation Index
> Fetch the complete documentation index at: https://labs.prompthon.io/llms.txt
> Use this file to discover all available pages before exploring further.
# GitHub Issue Guide
Use a GitHub issue when you have a concrete repository work item, not just an
early question.
If the request is still exploratory, use [Support](https://github.com/Prompthon-IO/agent-systems-handbook/blob/main/SUPPORT.md) or the
community Discord first. If the work is already scoped, use the matching issue
form so the request lands in a reviewable shape.
For the full sequence from support question to issue claim, fork or branch, and
pull request, use [Basic GitHub Flow For Contributors](/contributor-kit/contribution-workflow).
## Choose the right issue form
* `Content Proposal`: new lab pages, major revisions, radar notes, curated
reference notes, or publication follow-ons
* `Source Project Proposal`: new or substantially revised repo-owned starters
or examples under an allowed lane-local `examples/` folder
* `Practitioner Skill Package`: new or substantially revised local-agent
workflow packages under `skills/`. These are code-plus-docs contributions,
not documentation-only issues.
* `Repository Feature Or Process Proposal`: feature requests for repository
workflows, issue intake, templates, labels, review rules, contributor
documentation, or maintainer operations
* `Bug Or Broken Surface Report`: broken links, factual problems, example
defects, template issues, or repository workflow regressions
Each form asks for a Prompthon contribution track and work kind. Repository
automation turns those answers into `track:*`, `kind:*`, and
`status: pending-review` labels so contributors do not need label permissions.
## Issue writing standard
* Keep one issue focused on one outcome.
* Name the exact affected path, surface, or workflow.
* Describe the current problem before jumping to the fix.
* Propose the smallest clear change that would solve the problem.
* Add success criteria so reviewers can tell when the work is done.
* Link the relevant repo docs, templates, or existing pages.
* For content-oriented work, include source lineage instead of dropping in raw
upstream material.
## Claiming an issue
A claim should be visible on the issue itself. Use the assignee field only when
the maintainer wants to mark an internal contributor as actively responsible
for the task.
For public contributors who are not internal contributors yet, use an issue
comment as the public claim request:
```md theme={null}
Claim request:
- GitHub username:
- Planned scope:
- Expected first update:
```
Maintainers can acknowledge the claim in a reply and add the `claimed` label.
Leave the GitHub assignee field empty unless the contributor is already an
internal contributor for this repository. If the work goes quiet, a maintainer
can remove the label or assignee and leave a short status comment reopening the
task.
GitHub's native assignment feature is permission-bound: people with write access
can assign issues, and assignable users include yourself, commenters, users
with write access, and organization members with read access. In this
repository, an assignee is treated as an internal-contributor signal.
After the claim is acknowledged, follow
[Basic GitHub Flow For Contributors](/contributor-kit/contribution-workflow)
for the fork, branch, pull request, and review steps.
## What a good skill package issue includes
Use the `Practitioner Skill Package` form when the work creates or revises an
installable local-agent workflow package under `skills/`.
Good submissions usually include:
* the user-facing workflows the skill should support
* the local state, APIs, browser tools, or filesystem access it needs
* the expected `skills//` package shape
* a human-facing `README.md` that explains why the skill exists, who it is
for, and how the workflow works end-to-end
* an agent-facing `SKILL.md` that defines when Codex should invoke it
* safety, privacy, and generated-artifact boundaries
* concrete acceptance criteria for both instructions and helper code
## What a good feature request includes
Use the `Repository Feature Or Process Proposal` form when the request is
really about how this repository should work.
Good submissions usually include:
* the maintainer or contributor pain point
* the proposed repository-level change
* the surfaces affected by the change
* tradeoffs, migration costs, or reasons to defer
* a concrete definition of success
## Title examples
* `[Feature/Process]: Add a public guide for choosing GitHub issue forms`
* `[Content]: Add a systems page on agent evaluation loops`
* `[Source Project]: Add a minimal deep-research-agent starter`
* `[Practitioner Skill]: Add a Daily News Watcher skill package`
* `[Bug]: Fix the broken contributor-kit link in README.md`
## Before you submit
* Review [Contributing](https://github.com/Prompthon-IO/agent-systems-handbook/blob/main/CONTRIBUTING.md).
* Check the [Contributor Kit](/contributor-kit) for the matching template or guide.
* Search open issues so you do not file a duplicate.
* Prefer exact repo paths over general descriptions.
* If you are unsure whether the request belongs here yet, use
[Support](https://github.com/Prompthon-IO/agent-systems-handbook/blob/main/SUPPORT.md) first.
## Example feature request
If you want to propose a repository feature around issue intake, structure it
like this in the `Repository Feature Or Process Proposal` form:
* `Current problem`: Contributors can find the issue forms, but it is not clear
which form counts as a feature request versus a content proposal.
* `Proposed change`: Add a public GitHub issue guide in `contributor-kit/`,
link it from `CONTRIBUTING.md`, `SUPPORT.md`, and the issue chooser, and make
the process form explicitly mention repository feature requests.
* `Affected surfaces`: Issue intake, contributor documentation
* `Tradeoffs and risks`: Slightly more contributor documentation to maintain,
but much less ambiguity during issue intake
* `What success looks like`: A new contributor can choose the correct issue form
without asking a maintainer for routing help