From 7c12d6e35d9e1cc28f71877559c17b4088f32532 Mon Sep 17 00:00:00 2001
From: Mitchell Hashimoto <m@mitchellh.com>
Date: Sat, 14 Mar 2026 14:55:33 -0700
Subject: [PATCH] agents: skill for writing commit messages

---
 .agents/commands/gh-issue                     | 64 -------------------
 .../skills/writing-commit-messages/SKILL.md   | 62 ++++++++++++++++++
 2 files changed, 62 insertions(+), 64 deletions(-)
 delete mode 100755 .agents/commands/gh-issue
 create mode 100644 .agents/skills/writing-commit-messages/SKILL.md

diff --git a/.agents/commands/gh-issue b/.agents/commands/gh-issue
deleted file mode 100755
index de2f37335..000000000
--- a/.agents/commands/gh-issue
+++ /dev/null
@@ -1,64 +0,0 @@
-#!/usr/bin/env nu
-
-# A command to generate an agent prompt to diagnose and formulate 
-# a plan for resolving a GitHub issue.
-#
-# IMPORTANT: This command is prompted to NOT write any code and to ONLY
-# produce a plan. You should still be vigilant when running this but that
-# is the expected behavior.
-# 
-# The `<issue>` parameter can be either an issue number or a full GitHub
-# issue URL.
-def main [
-  issue: any, # Ghostty issue number or URL
-  --repo: string = "ghostty-org/ghostty" # GitHub repository in the format "owner/repo"
-] {
-  # TODO: This whole script doesn't handle errors very well. I actually
-  # don't know Nu well enough to know the proper way to handle it all.
-  
-  let issueData = gh issue view $issue --json author,title,number,body,comments | from json
-  let comments = $issueData.comments | each { |comment|
-    $"
-### Comment by ($comment.author.login)
-($comment.body)
-" | str trim
-  } | str join "\n\n"
-
-  $"
-Deep-dive on this GitHub issue. Find the problem and generate a plan. 
-Do not write code. Explain the problem clearly and propose a comprehensive plan 
-to solve it.
-
-# ($issueData.title) \(($issueData.number)\)
-
-## Description
-($issueData.body)
-
-## Comments
-($comments)
-
-## Your Tasks
-
-You are an experienced software developer tasked with diagnosing issues.
-
-1. Review the issue context and details. 
-2. Examine the relevant parts of the codebase. Analyze the code thoroughly
-   until you have a solid understanding of how it works.
-3. Explain the issue in detail, including the problem and its root cause.
-4. Create a comprehensive plan to solve the issue. The plan should include:
-   - Required code changes
-   - Potential impacts on other parts of the system
-   - Necessary tests to be written or updated
-   - Documentation updates
-   - Performance considerations
-   - Security implications
-   - Backwards compatibility \(if applicable\)
-   - Include the reference link to the source issue and any related discussions
-4. Think deeply about all aspects of the task. Consider edge cases, potential
-   challenges, and best practices for addressing the issue. Review the plan 
-   with the oracle and adjust it based on its feedback.
-
-**ONLY CREATE A PLAN. DO NOT WRITE ANY CODE.** Your task is to create
-a thorough, comprehensive strategy for understanding and resolving the issue.
-" | str trim
-}
diff --git a/.agents/skills/writing-commit-messages/SKILL.md b/.agents/skills/writing-commit-messages/SKILL.md
new file mode 100644
index 000000000..dedadbe5e
--- /dev/null
+++ b/.agents/skills/writing-commit-messages/SKILL.md
@@ -0,0 +1,62 @@
+---
+name: writing-commit-messages
+description: >-
+  Writes Git commit messages. Activates when the user asks to write
+  a commit message, draft a commit message, or similar.
+---
+
+# Writing Commit Messages
+
+Write commit messages that follow commit style guidelines for the project.
+
+## Format
+
+```
+<subsystem>: <summary>
+
+<reference issues/PRs/etc.>
+
+<long form description>
+```
+
+## Rules
+
+### Subject line
+
+- **Subsystem prefix**: Use a short, lowercase identifier for the
+  area of code changed (e.g., `terminal`, `vt`, `lib`, `config`,
+  `font`). Determine this from the file paths in the diff. If
+  changes span the macOS app, use `macos`. For GTK, use `gtk`. For
+  build system, use `build`. Use nested subsystems with `/` when
+  helpful and exclusive (e.g., `terminal/osc`).
+- **Summary**: Lowercase start (not capitalized), imperative mood,
+  no trailing period. Keep it concise—ideally under 60 characters
+  total for the whole subject line.
+
+### References
+
+- If the change relates to a GitHub issue, PR, or discussion, list
+  the relevant numbers on their own lines after the subject, separated
+  by a blank line. E.g. `#1234`
+- If there are no references, omit this section entirely (no blank
+  line).
+
+### Long form description
+
+- Describe **what changed**, **what the previous behavior was**,
+  and **how the new behavior works** at a high level.
+- Use plain prose, not bullet points. Wrap lines at ~72 characters.
+- Focus on the _why_ and _how_ rather than restating the diff.
+- Keep the tone direct and technical without no filler phrases.
+- Don't exceed a handful of paragraphs; less is more.
+
+## Workflow
+
+- If `.jj` is present, use `jj` instead of `git` for all commands.
+- Run a diff to see what changes are present since the last commit.
+- Identify the subsystem from the changed file paths.
+- Identify any referenced issues/PRs from the diff context or
+  branch name.
+- Draft the commit message following the format above.
+- Apply the commit
+- Don't push the commit; leave that to the user.