Agent skill

Simple Issue Description

by every-app in every-app/open-seo

Turn a rough bug report, feature request, support note, or pull request into a short, plain-language issue focused on the problem and desired behavior.

MITAuto-check passedDevelopment

Install Simple Issue Description

skills CLI
$ npx skills add every-app/open-seo --skill simple-issue-description -a claude-code

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

GitHub CLI
$ gh skill install every-app/open-seo simple-issue-description --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/every-app/open-seo.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/simple-issue-description .claude/skills/simple-issue-description && 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
simple-issue-description
GitHub stars
23k
Used in
1 other repo
Token cost
~1.2k tokens
SKILL.md length
543 words
Files
2
Skills in repo
19
Repo updated
First seen
Licence
MIT

At a glance

Turn a rough bug report, feature request, support note, or pull request into a short, plain-language issue focused on the problem and desired behavior.

  • Works in 6 steps: Read the supplied notes, conversation,… → Identify the concrete problem. State who… → Describe the desired behavior without… → …
  • A contributor asks to simplify an issue
  • SKILL.md covers Workflow, Writing rules, Output format and Example
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Simple Issue Description is an agent skill from every-app/open-seo. Turn a rough bug report, feature request, support note, or pull request into a short, plain-language issue focused on the problem and desired behavior. Use when a contributor asks to simplify an issue, explain what a PR is for, create the corresponding issue for a PR, remove implementation detail from a report, or invokes /simple-issue-description.

Its SKILL.md is about 1.2k tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files (for example `agents/openai.yaml`).

It sits in Development, covering Plain language and style rules, Pull requests and QA and bug reports. The repository describes itself as: Open source alternative to Semrush and Ahrefs. The licence is MIT.

When your agent uses it

  • A contributor asks to simplify an issue
  • Explain what a PR is for
  • Create the corresponding issue for a PR
  • Remove implementation detail from a report

Example prompts

  • “/simple-issue-description”

Workflow steps

6 steps, taken from the first numbered list in SKILL.md.

  1. Read the supplied notes, conversation, issue, PR description, or diff. In a PR, also check for spec, design doc, or README changes — they…
  2. Identify the concrete problem. State who or what is affected when the source makes that clear.
  3. Describe the desired behavior without prescribing an implementation.
  4. Keep only context that helps someone understand or reproduce the problem.
  5. If the source is a PR or diff, describe the problem the change tries to solve, not the files or code it changes.
  6. Draft the issue immediately unless the problem and desired behavior cannot be determined. In that case, ask one short clarifying question.

What it can do on your machine

Read from SKILL.md and the folder at commit deb4491. 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

    No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown).

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

  • Network

    No URLs in SKILL.md.

    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

Simple Issue Description loads about 1.2k tokens when it runs. Until then it costs about 94 tokens; SKILL.md has 543 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~94
When it runs · the whole SKILL.md, loaded when a task matches
~1.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 every-app/open-seo at commit deb4491, republished under its MIT licence (© every-app). 543 words, ~1,174 tokens.

Download SKILL.mdSave it as .claude/skills/simple-issue-description/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
simple-issue-description
description
Turn a rough bug report, feature request, support note, or pull request into a short, plain-language issue focused on the problem and desired behavior. Use when a contributor asks to simplify an issue, explain what a PR is for, create the corresponding issue for a PR, remove implementation detail from a report, or invokes /simple-issue-description.

Simple Issue Description

Write an issue a maintainer can understand in under a minute. Focus on what someone experiences and what should happen instead.

Workflow

  1. Read the supplied notes, conversation, issue, PR description, or diff. In a PR, also check for spec, design doc, or README changes — they often state the intent better than the description does.
  2. Identify the concrete problem. State who or what is affected when the source makes that clear.
  3. Describe the desired behavior without prescribing an implementation.
  4. Keep only context that helps someone understand or reproduce the problem.
  5. If the source is a PR or diff, describe the problem the change tries to solve, not the files or code it changes.
  6. Draft the issue immediately unless the problem and desired behavior cannot be determined. In that case, ask one short clarifying question.

One issue per problem. If the source bundles unrelated problems, draft the issue for the most significant one, list the others in a line each, and tell the contributor to split them into separate issues and separate pull requests.

If the source adds a capability instead of fixing a misbehavior, do not stage the absence as a bug. Describe what a user cannot do today and the full user experience of the feature: who uses it, from where, and what they see.

Do not invent user impact, reproduction steps, or certainty that the source does not support. If the source only shows cleanup, refactoring, or a possible code smell, say that no concrete problem is clear instead of manufacturing an issue — this rule wins over step 6. Reply with two or three sentences: what the source shows, and what evidence would make it issue-worthy.

If the source fixes a security weakness that is not already public, do not draft a public issue describing it. Suggest reporting it privately to the maintainer instead.

Show full SKILL.md (229 more words)Show less

Writing rules

  • Use plain language and short sentences.
  • Keep the issue under 200 words unless it is clear that more is necessary to describe the reproduction steps or a large feature.
  • Lead with behavior, not code, architecture, or the proposed fix. A one-sentence plain-language cause is fine when the symptom cannot be understood without it.
  • Keep technical details only when they are necessary to reproduce or understand the problem. Limits and defaults that make the symptom make sense (batch sizes, quotas, caps) count as necessary.
  • Preserve useful evidence such as error messages, screenshots, links, and documentation references.
  • Do not mention that AI wrote or reviewed the issue.
  • Avoid filler, praise, roadmap language, and exhaustive edge cases.
  • Use the contributor's level of certainty. Do not present a guess as a confirmed bug; write "can" or "appears to" when the source describes a risk rather than an observed failure.

Output format

The first line is the issue title — when filing on GitHub, put it in the title field instead of repeating it in the body. For a missing capability, title the outcome ("Flag pages with no structured data") rather than a fake bug ("Audits never mention structured data").

Omit the Extra context section when there is nothing useful to add. Constraints and scope notes belong there, including what is not affected when a maintainer would reasonably worry that it is.

markdown
# <Short title describing the problem or desired outcome>

## TL;DR

<In one or two sentences, explain what happens now and what should happen instead.>

## What is happening?

<Describe the current behavior in plain language. Include a concrete example when available.>

## What should happen?

<Describe the desired behavior without proposing how to build it.>

## Extra context

<Optional reproduction steps, error text, screenshots, links, or constraints.>

Example

markdown
# The chat jumps away from messages I am reading

## TL;DR

When I scroll up to read an older message, a new response moves me back to the bottom of the chat. The chat should stay where I left it until I choose to return to the latest message.

## What is happening?

New responses automatically scroll the chat to the bottom, even when I am reading earlier messages.

## What should happen?

Keep my current scroll position and show that a new message is available.

© every-app, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file in .agents/skills/simple-issue-description of every-app/open-seo.

  • SKILL.md
  • agents/openai.yaml

Open the folder on GitHubat commit deb4491

Used in 1 other repository

We found 1 copy of this SKILL.md (exact, near-identical or edited) in other folders, from 1 other GitHub owner. This page covers the copy in every-app/open-seo, which our catalogue first saw on October 7, 2026.

Compare with similar skills

Simple Issue Description 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.

Simple Issue Description compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Simple Issue Description this skillevery-app/open-seo23k1 repos~1.2kAutomated safety check: PassMIT
Community Triageroryeckel/wyoming_openai218—~2.9kAutomated safety check: PassApache-2.0
Issue BriefVasiHemanth/tokentelemetry376—~1.5kAutomated safety check: PassMIT
Handsontable Demo Page Generatorhandsontable/handsontable22k—~1.8kAutomated safety check: PassCustom licence
Moai Workflow Testingmodu-ai/moai-adk1.2k—~2.7kAutomated safety check: PassApache-2.0
Explain This PRVarnan-Tech/opendirectory672—~1.2kAutomated safety check: PassMIT

Similar skills

  • Community Triage

    roryeckel/wyoming_openai

    GitHub issues, pull requests, bug reports, scope questions, and support threads.

    218 GitHub stars~2.9k tokensUpdated 3 days ago
    DevelopmentAuto-check passed
  • Issue Brief

    VasiHemanth/tokentelemetry

    Explain a GitHub issue, discussion, or feature request in plain language before deciding whether to build it.

    376 GitHub stars~1.5k tokensUpdated yesterday
    DevelopmentAuto-check passed
  • Handsontable Demo Page Generator

    handsontable/handsontable

    Builds two throwaway HTML test pages for a Handsontable pull request, one on the released CDN version and one on the local build, to compare behavior side by side.

    22k GitHub stars~1.8k tokensUpdated today
    DevelopmentAuto-check passed
  • Moai Workflow Testing

    modu-ai/moai-adk

    A skill your agent uses when writing tests, measuring coverage, or running characterization, performance, or PR-review QA.

    1.2k GitHub stars~2.7k tokensUpdated today
    DevelopmentAuto-check passed
  • Explain This PR

    Varnan-Tech/opendirectory

    Takes a GitHub PR URL or the current branch and writes a plain-English explanation of what it does and why, then posts it as a PR comment.

    672 GitHub stars~1.2k tokensUpdated 1 mo ago
    DevelopmentAuto-check passed
  • Opensource Contributions

    magnus919/hermes-profiles

    Make good open source contributions — check CONTRIBUTING.md first, follow project norms, be a good citizen.

    278 GitHub stars~1.4k tokensUpdated 3 mo ago
    DevelopmentAuto-check passed

More from every-app/open-seo

All 19 skills in this repo
  • Papercuts

    every-app/open-seo

    Log genuine, recurring repository friction to .agents/PAPERCUTS.md — confusing setup, a flaky repo command or script, a misleading in-repo error, stale generated files, or a non-obvious gotcha that…

    23k GitHub starsUsed in 1 repo~1.2k tokens
    Auto-check passed
  • Evaluate Skill

    every-app/open-seo

    Test a candidate OpenSEO skill end to end by running fresh, isolated Codex sessions against the local backend and scoring the reports they save.

    23k GitHub stars~1.8k tokensUpdated yesterday
    Auto-check: notes
  • Create Repo Skill

    every-app/open-seo

    Create or update a skill in this repository the right way — canonical home in .agents/skills, internal-vs-public marking, symlink mirroring into .claude/skills, and public docs registration for…

    23k GitHub stars~1.4k tokensUpdated yesterday
    Auto-check passed
  • Deslop

    every-app/open-seo

    Remove AI writing patterns from prose so it reads like a person wrote it.

    23k GitHub stars~602 tokensUpdated yesterday
    Auto-check passed
  • Observability Triage

    every-app/open-seo

    Triage OpenSEO production errors in Cloudflare Workers Observability — verified query recipes, counting gotchas, and a known-noise filter list applied automatically.

    23k GitHub stars~1.7k tokensUpdated yesterday
    Auto-check passed
  • SEO Report

    every-app/open-seo

    Write and save an OpenSEO report as one self-contained HTML page.

    23k GitHub stars~5.4k tokensUpdated yesterday
    Auto-check passed

Questions about Simple Issue Description

What does Simple Issue Description do?

Turn a rough bug report, feature request, support note, or pull request into a short, plain-language issue focused on the problem and desired behavior. Simple Issue Description is an agent skill from every-app/open-seo. Turn a rough bug report, feature request, support note, or pull request into a short, plain-language issue focused on the problem and desired behavior.

When should I use Simple Issue Description?

Simple Issue Description fits situations like: A contributor asks to simplify an issue; explain what a PR is for; create the corresponding issue for a PR; remove implementation detail from a report.

How do I install Simple Issue Description in Claude Code?

Run `npx skills add every-app/open-seo --skill simple-issue-description -a claude-code`. Or copy the skill folder (.agents/skills/simple-issue-description in every-app/open-seo) into .claude/skills/simple-issue-description in your project. Claude Code loads it when a task matches its description.

How do I install Simple Issue Description in Codex?

Run `npx skills add every-app/open-seo --skill simple-issue-description -a codex`. Or copy the skill folder (.agents/skills/simple-issue-description in every-app/open-seo) into .agents/skills/simple-issue-description in your project. Codex loads it when a task matches its description.

Can I use Simple Issue Description 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 every-app/open-seo --skill simple-issue-description -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/simple-issue-description, .gemini/skills/simple-issue-description, .github/skills/simple-issue-description and .opencode/skills/simple-issue-description in your project.

What does Simple Issue Description need to run?

SKILL.md names no scripts, command-line tools or credentials: Simple Issue Description is instructions for the agent only.

Does Simple Issue Description access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Simple Issue Description 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 Simple Issue Description use?

Simple Issue Description is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Simple Issue Description use?

About 1.2k tokens (SKILL.md is roughly 4.7k 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 Simple Issue Description?

Skills that share tags, products or a category with Simple Issue Description: Community Triage (roryeckel/wyoming_openai, 218 stars), Issue Brief (VasiHemanth/tokentelemetry, 376 stars), Handsontable Demo Page Generator (handsontable/handsontable, 22k stars) and Moai Workflow Testing (modu-ai/moai-adk, 1.2k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Simple Issue Description?

every-app (a GitHub organization) maintains it in every-app/open-seo, which has 22,587 GitHub stars. The repository holds 19 skills in this directory. The repository was last updated on October 6, 2026.

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