Clarify contribution and pull request guidance (#457)

.agents/skills/simple-issue-description/SKILL.md

@@ -0,0 +1,80 @@
+---
+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.
+
+## 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.
+```

.agents/skills/simple-issue-description/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Simple Issue Description"
+  short_description: "Turn rough reports into clear, simple issues"
+  default_prompt: "Use $simple-issue-description to turn this report or PR into a clear issue focused on the problem and desired behavior."

README.md

@@ -64,7 +64,15 @@ See [`docs/LOCAL_DEVELOPMENT.md`](./docs/LOCAL_DEVELOPMENT.md).
 
 ## Contributing
 
-Contributions are very welcome. See [`docs/CONTRIBUTING.md`](./docs/CONTRIBUTING.md).
+Creating clear issues is the best way to contribute.
+
+Read more here: [`docs/CONTRIBUTING.md`](./docs/CONTRIBUTING.md)
+
+We have this skill: `/simple-issue-description` which helps.
+
+```sh
+npx skills add every-app/open-seo --skill simple-issue-description
+```
 
 ## Community
 

docs/CONTRIBUTING.md

@@ -1,33 +1,62 @@
 # Contributing to OpenSEO
 
-Contributions are very welcome.
+Thank you for your interest in contributing to OpenSEO!
 
-- Open an issue for bugs, UX friction, or feature requests.
+We deeply appreciate the time and enthusiasm that people bring to the project. One of my favorite things is seeing the forks that people make building off of OpenSEO.
-- Open a PR if you want to implement a feature directly.
-- Community-driven improvements are prioritized, and high-quality PRs are encouraged.
 
-If you want to contribute but are unsure where to start, open an issue and describe what you want to build. You can also join the [Discord](https://discord.gg/c9uGs3cFXr) to talk through ideas first.
+## Why aren't we accepting PRs?
 
-## Local development
+Short Answer: AI & Security
 
-See [LOCAL_DEVELOPMENT.md](./LOCAL_DEVELOPMENT.md) for how to run the app locally.
+I love using AI to write code as much as anyone. But, it makes it very challenging to assess how much thought and effort went into external pull requests. As a result, I spend a lot of time reviewing, testing and iterating on many external PRs and it ends up slowing down overall development.
 
-## Guidelines
+Additionally, as OpenSEO becomes more popular, I'm concerned about malicious contributors attempting to sneak in code that slips through review.
 
-- Keep PRs focused: one feature or fix per PR.
+## Issues: The best way to contribute
-- For larger features, open an issue first so we can align on the approach before you invest time.
+
-- Before requesting review, run the same root checks used by CI:
+A succinct, clearly written issue describing the problem your facing and your desired behavior is worth its weight in gold.
+
+This is much easier for me to review than a PR. If its something that I think a coding agent can easily build, I'll have my own agent build it right away. If it's something bigger, I'll add it to the roadmap.
+
+### Can I still make PRs?
+
+Yup! I just won't merge them right now. But, making a PR can be a good way to improve the quality of your issue. I'm much more likely to prioritize implementing something myself if you've already created a proof of concept for an integration or built a great UI for me to take inspiration from.
+
+Videos demoing the feature also help a lot here too since its a sign that the PR wasn't just made by Claude and never tested.
+
+### /simple-issue-description
+
+For ease of review, I would appreciate if you used the `/simple-issue-description` to refine your issue. I'm hoping that everything being written in the same voice and format will make it easier to understand issues without a lot of back and forth.
+
+Install it with:
 
 ```sh
-  pnpm ci:check
+npx skills add every-app/open-seo --skill simple-issue-description
-  pnpm test:ci
-  pnpm vite build
 ```
 
-- If you changed the website under `web/`, also run:
+See [Set up OpenSEO Agent Skills](https://openseo.so/docs/skills/setup) for other install options.
 
-  ```sh
+Here is what we're aiming for with `/simple-issue-description`:
-  pnpm --dir web install --frozen-lockfile
+
-  pnpm --dir web run types:check
+- There is sufficient detail in the issue.
-  pnpm --dir web run build
+  - What is the problem you're facing?
-  ```
+  - What is the full user experience for the feature you're proposing?
+- Succinct i.e. not default Claude output.
+  - I have an `/explain-simply` skill I use all the time which inspired `/simple-issue-description`
+  - I can't understand the default Claude / Codex output at this point.
+
+### Our Roadmap
+
+Here is a link to our Roadmap: http://openseo.so/roadmap
+
+These are planned features and improvements. If you'd like to create an issue and give your thoughts on what would make these features great, I'm all ears!
+
+## Wrapping Up
+
+I know that this may be disappointing for some people. I hope that in 6 months, we have some awesome review process that alleviates my concerns leading to current process.
+
+If you would like to be more involved though, the best way is to [Join our Discord](https://discord.com/invite/c9uGs3cFXr) :
+
+- Help others when they ask questions
+- Share your experiences doing SEO
+- Share things you learned while building your fork