Freshell contribution skill

[danshapiro]

Problem

When users hit a Freshell bug, we often miss high-quality issue reports unless the user already knows to file one and knows what details to include.

We want agents (Claude/Codex) to help users file issues, but only when appropriate, and without being noisy/annoying.

Proposal: freshell-contribution skill

Create a skill focused on helping users report Freshell bugs effectively.

Trigger (frontmatter intent)

Use when the user appears to be experiencing a problem with Freshell itself and may benefit from filing a GitHub issue.

Rough frontmatter description requested:

• "run this skill when the user experiences a problem with freshell itself"

Desired behavior

1. Detect likely Freshell bug/problem scenario.
2. Offer help filing a GitHub issue (do not auto-file without consent).
3. If user agrees:
   • Gather details needed for a high-quality issue.
   • Produce a strong issue body (clear repro, expected/actual, env, logs, impact).
   • File issue if GitHub auth is available.
4. If user agrees but auth is missing:
   • Walk user through GitHub CLI auth setup.
   • Then file (or provide copy/paste-ready body if user prefers manual).

"Good issue" guidance the skill should enforce

• Clear summary/title
• User scenario and impact
• Exact repro steps
• Expected vs actual behavior
• Environment/context (OS, shell, Freshell version, ports/instances)
• Relevant logs/errors/IDs
• Suspected root cause (if known)
• Proposed fix direction (optional)

Guardrails (to avoid annoyance)

• Ask at most once per problem thread unless user reopens the topic.
• Do not suggest issue filing for non-Freshell tasks.
• Do not interrupt active implementation unless user asks or bug is blocking.
• Respect user decline and do not re-prompt repeatedly.

Acceptance criteria

• In Freshell bug conversations, agent offers issue help appropriately.
• In unrelated conversations, no issue-filing suggestion appears.
• If user agrees and gh is authenticated, issue is created and URL returned.
• If user agrees and gh is not authenticated, agent provides concise auth steps and continues.
• Generated issue quality is consistently high and actionable.

Rollout/testing request

We should test this ourselves for a while before shipping broadly, since over-triggering could be annoying.

Suggested test plan:

• Run internal dogfood sessions across mixed conversation types.
• Track false-positive suggestion rate and user annoyance signals.
• Tune trigger description/guardrails before enabling by default.

Implementation notes

Likely add a new skill under our skills set (Claude/Codex) with:

• minimal frontmatter trigger text
• explicit consent-first workflow
• issue quality checklist/template
• auth fallback flow (gh auth status -> gh auth login guidance)