@moon791017/neo-skills 1.1.13 → 1.1.15

package/README.md

@@ -30,7 +30,7 @@
 | 漸進式揭露 | Agent 啟動時只讀 `name` 與 `description`；真正需要時才讀完整 `SKILL.md` 與 references。 |
 | 觸發導向描述 | 每個 skill 的 `description` 都說明「何時使用」，提升自動觸發準確度。 |
 | 外部知識庫 | 詳細規則放在 `references/` 或 `reference/`，避免主技能檔過長。 |
-| 可重用資源 | 透過 `assets/`、`templates/` 與 `scripts/` 提供可落地的產出基礎。 |
+| 可重用資源 | 透過 `assets/`、`templates/` 與 `scripts/` 提供可實踐的產出基礎。 |
 | 可驗證結構 | 使用 `scripts/check-skills-syntax.py` 檢查技能名稱、frontmatter 與基本規格。 |
 
 ## 內建技能
@@ -60,14 +60,18 @@
 | Vue | `neo-vue` | 建置、除錯、重構或審查 Vue 3、SFC、Composition API、Pinia、Vue Router、Vite 與 Vue+TypeScript。 |
 | Agent 架構 | `neo-sub-agent` | 設計、建立、審查或轉換 sub-agent、custom agent、worker/reviewer/planner agent 或 multi-agent workflow。 |
 | Agent 架構 | `neo-agentic-design` | 設計、評估或實作 Agent 工作流、提示詞鏈、路由、規劃、反思、多 Agent 協作與記憶體管理等框架無關模式。 |
+| 技能開發 | `generate-skill` | 建立、更新、審查或最佳化 Agent Skill，包含規格、觸發描述、延伸資源、評估資料與設計模式。 |
 | 可觀測性 | `neo-opentelemetry` | 解釋 OpenTelemetry 概念、規劃或審查 Collector 架構與設定、處理維運排障、安全、零程式 instrumentation 及相容性遷移。 |
 | 文字潤飾 | `neo-stop-slop` | 去除繁中或英文中的 AI 腔、贅詞、公式化句式，支援文件、註解、commit message 與 PR 說明。 |
+| PR 產出 | `neo-pr` | 詢問或自動偵測 Repository 來源與目標分支，擷取變更並產生重點式且去 AI 腔的 PR Title 與 PR Description。 |
+
+`generate-skill` 位於 `.agents/skills/`，可由 Agent Skills CLI 探索與安裝；其餘技能位於 `skills/`。
 
 ## 安裝
 
 ### Antigravity CLI 全域安裝
 
-同步所有技能到 `~/.gemini/antigravity-cli/skills`：
+同步 `skills/` 下的技能到 `~/.gemini/antigravity-cli/skills`：
 
 ```bash
 npx -y @moon791017/neo-skills@latest
@@ -81,24 +85,48 @@ node bin/install-skills.js
 
 ### Agent Skills CLI 安裝
 
-安裝全部技能：
+Agent Skills CLI 會從 GitHub repository 探索 `skills/` 與 `.agents/skills/`。請明確指定目標 Agent，避免使用 `--all` 時同時選取不支援全域安裝的 Agent。
+
+| Agent | `--agent` ID |
+| :--- | :--- |
+| Claude Code | `claude-code` |
+| Copilot CLI | `github-copilot` |
+| Codex | `codex` |
+| Antigravity CLI | `antigravity-cli` |
+
+安裝全部技能到目前專案（以 Codex 為例）：
 
 ```bash
-npx skills add Benknightdark/neo-skills --all
+npx skills add Benknightdark/neo-skills --skill '*' --agent codex -y
 ```
 
-安裝到全域：
+安裝全部技能到全域（以 Codex 為例）：
 
 ```bash
-npx skills add Benknightdark/neo-skills --all -g
+npx skills add Benknightdark/neo-skills --skill '*' --agent codex -g -y
 ```
 
-只安裝指定技能：
+同時安裝到多個 Agent 時，重複傳入 `--agent`：
 
 ```bash
-npx skills add Benknightdark/neo-skills --skill neo-typescript,neo-vue
+npx skills add Benknightdark/neo-skills --skill '*' \
+  --agent codex \
+  --agent antigravity-cli \
+  -g -y
 ```
 
+只安裝指定技能時，重複傳入 `--skill`：
+
+```bash
+npx skills add Benknightdark/neo-skills \
+  --skill neo-typescript \
+  --skill neo-vue \
+  --agent codex \
+  -y
+```
+
+> `--all` 等同同時選取全部技能與全部 Agent。不要使用 `--all -g` 表示「全域安裝全部技能」；Eve 與 PromptScript 僅支援專案範圍，會使該組合回報安裝失敗。
+
 ## 系統提示詞安裝
 
 Agent Skills 規格同步的是技能目錄；`AGENTS.md`、`CLAUDE.md`、Copilot instructions 或 Antigravity `agents.md` 這類指導檔需要另外安裝。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moon791017/neo-skills",
-  "version": "1.1.13",
+  "version": "1.1.15",
   "type": "module",
   "description": "Neo Skills: A Universal AI Agent Skills Extension",
   "homepage": "https://neo-blog-iota.vercel.app/",

package/skills/neo-pr/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: neo-pr
+description: >
+  Use this skill when the user asks to create, draft, review, format, or generate a Pull
+  Request (PR) title and description, specify target or source branches for a repository,
+  or convert git branch diffs into concise, high-impact, non-AI-slop PR content.
+license: MIT
+compatibility: Requires Python 3.10+ (uv or python3) for git-pr-extractor.py, and Node.js for analyze-slop.js validation.
+metadata:
+  author: Ben Knight Dark
+  version: "1.0.0"
+  patterns: generator, reviewer, inversion
+---
+
+# Neo PR Generator & Refiner
+
+`neo-pr` is an expert skill engineered to generate precise, concise, and non-AI-slop Pull Request (PR) titles and descriptions for Git repositories. It proactively guides the user to clarify repository and branch targets, extracts change histories, and outputs clear, highly structured PR content.
+
+---
+
+## Gotchas
+
+* **Non-existent or Unaligned Branches**: If the specified source or target branch does not exist locally or on remote, prompt the user to run `git fetch` or provide the correct branch name. Do not invent non-existent base branches.
+* **Overly Long Diffs and Token Overhead**: If the branch diff spans dozens of files or thousands of lines, inspect `git diff --stat` and commit logs first to gain high-level context instead of loading full diffs at once.
+* **De-slop Does Not Mean Removing Technical Substance**: When stripping AI fluff, eliminate throat-clearing openers (e.g., "It is worth noting that...", "This PR aims to..."), but strictly preserve essential context, key logic shifts, breaking changes, and test instructions.
+
+---
+
+## Workflow Checklist
+
+- [ ] **Step 1 — Perceive (Gather Branch & Repository Context)**: Identify the repository path, source branch (`source branch`), and target branch (`target branch`). If unspecified, prompt the user or detect the current Git state.
+- [ ] **Step 2 — Reason & Load References (Load Templates & Guidelines)**: Read [pr-template.md](file:///Users/ben/projects/neo-skills/skills/neo-pr/references/pr-template.md) for structural standards and de-slop conventions.
+- [ ] **Step 3 — Act: Extract Diff (Fetch Change Record)**: Execute the helper script `git-pr-extractor.py` to retrieve commit logs, file statistics, and diff snippets.
+- [ ] **Step 4 — Act: Generate & De-slop (Produce Concise PR Content)**: Write a Conventional Commits title and bulleted PR description while eliminating all AI tells.
+- [ ] **Step 5 — Verify (Quality Check)**: Verify that the generated title and description adhere to de-slop standards (optionally run `analyze-slop.js` to score density).
+
+---
+
+## Detailed Guidelines
+
+### Step 1 — Perceive (Gather Branch & Repository Context)
+
+Determine the following core parameters:
+1. **Repository Context**: Current working directory or specified GitHub/GitLab workspace.
+2. **Source Branch**: Branch containing the new changes (e.g., `feature/user-auth` or current checked-out branch).
+3. **Target Branch**: Base branch to merge into (e.g., `main`, `master`, or `develop`).
+
+If the user has not specified branches, ask with a concise prompt:
+> "Please specify your **source branch** (e.g., `feature/xxx`) and **target branch** (e.g., `main` or `develop`). If omitted, I will default to PRing the current branch into `main`."
+
+---
+
+### Step 2 — Reason & Load References
+
+Load relevant design documents based on diff scope:
+* **PR Structure & Template**: Read `references/pr-template.md` for standard markdown sections.
+* **De-slop Rules**: Apply core `neo-stop-slop` principles (active voice, remove filler phrases, focus on objective facts).
+
+---
+
+### Step 3 — Act: Extract Diff (Fetch Change Record)
+
+Run `git-pr-extractor.py` non-interactively in the target repository directory:
+```bash
+python3 skills/neo-pr/scripts/git-pr-extractor.py --target-branch <target> --source-branch <source>
+```
+
+Alternatively, run native Git commands if script execution is unavailable:
+```bash
+git log <target>..<source> --oneline
+git diff <target>..<source> --stat
+```
+
+---
+
+### Step 4 — Act: Generate & De-slop (Produce Concise PR Content)
+
+Construct the PR Title and Description based on extracted commit and diff context.
+
+#### 1. PR Title Standard (Conventional Commits)
+* Format: `<type>(<scope>): <short summary>`
+* Example: `feat(auth): add JWT authorization and automatic token refresh`
+* Rules:
+  - Do not begin with filler phrases ("This PR implements...", "A commit to...").
+  - Keep under 50 characters, imperative mood, direct and actionable.
+
+#### 2. PR Description Standard (Bulleted Structure)
+The PR body must contain the following four sections, formatted strictly with **bullet points**:
+
+```markdown
+## 📌 Motivation
+- Explain why this change is required, the bug it resolves, or feature requirement it fulfills.
+
+## 🛠️ Key Changes
+- Highlight primary modification points (list critical module/file updates and structural logic shifts).
+- Avoid line-by-line code repetition; focus on high-level architecture and logic evolution.
+
+## ⚠️ Impact & Breaking Changes
+- Note any breaking changes, API contract updates, or database schema migrations.
+- Write `None` if there is no significant impact.
+
+## 🧪 Verification & Test Steps
+- List passed unit tests or manual verification steps (including exact execution commands).
+```
+
+#### 3. Strict De-slop Rules
+* ❌ Never use: "It is worth noting that", "Needless to say", "This PR aims to", "In summary", "Clearly".
+* ❌ Avoid hyperbolic fluff: "dramatically improves", "seamlessly integrates", "highly robust".
+* ⭕ Use concrete facts & metrics: "reduces response latency by 30ms", "fixes NullReferenceException on null payload".
+
+---
+
+### Step 5 — Verify (Quality Check)
+
+1. Ensure no critical modifications are omitted from the generated title or description.
+2. Run de-slop score check if `skills/neo-stop-slop/scripts/analyze-slop.js` is available:
+   ```bash
+   node skills/neo-stop-slop/scripts/analyze-slop.js --input "<generated PR description>" --format json
+   ```
+   Confirm `slopDensityScore` is **under 0.5%** (Grade **A+**).

package/skills/neo-pr/evals/eval_queries.json

@@ -0,0 +1,14 @@
+{
+  "should_trigger": [
+    "Help me generate a PR title and description for merging feature/user-auth into main",
+    "Draft a clean, bulleted Pull Request description with no AI slop",
+    "Ask me for source and target branches, then generate concise PR content",
+    "Extract git diff and output a structured PR title and body"
+  ],
+  "should_not_trigger": [
+    "Perform a code review on this file and report security risks",
+    "Run git status to show my current uncommitted changes",
+    "Write a git commit message for fixing the crash bug",
+    "Rewrite this technical blog post to remove AI tells"
+  ]
+}

package/skills/neo-pr/evals/evals.json

@@ -0,0 +1,16 @@
+{
+  "skill_name": "neo-pr",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Generate a concise, non-AI-slop PR title and description for merging feature/user-auth into main.",
+      "expected_output": "A PR title adhering to Conventional Commits format, and a bulleted markdown PR description covering Motivation, Key Changes, Impact & Breaking Changes, and Verification & Test Steps with no AI fluff phrases.",
+      "assertions": [
+        "PR Title complies with Conventional Commits format",
+        "PR Description includes Motivation, Key Changes, Impact & Breaking Changes, and Verification sections",
+        "Content is structured strictly with bullet points",
+        "Does not contain AI tells like 'It is worth noting that' or 'This PR aims to'"
+      ]
+    }
+  ]
+}

package/skills/neo-pr/references/pr-template.md

@@ -0,0 +1,61 @@
+# PR Title & Description Standard Reference
+
+This document serves as the standard PR output template and Anti-Slop writing reference for the `neo-pr` skill.
+
+---
+
+## 1. PR Title Standard (Conventional Commits)
+
+Titles must be clear, concise, and directly reflect the underlying changes using Conventional Commits format:
+
+`<type>(<scope>): <description>`
+
+### Common Types:
+* `feat`: A new feature
+* `fix`: A bug fix
+* `refactor`: A code change that neither fixes a bug nor adds a feature
+* `docs`: Documentation changes only
+* `test`: Adding missing tests or correcting existing tests
+* `chore`: Changes to the build process, auxiliary tools, or dependencies
+* `perf`: A code change that improves performance
+
+### Title Examples:
+- ✅ `feat(auth): add Google OAuth login flow and token handler`
+- ✅ `fix(cart): resolve overflow in checkout discount calculation`
+- ✅ `refactor(db): extract user repository to domain service layer`
+- ❌ `Updated some code` (Too vague)
+- ❌ `feat(auth): this PR dramatically improves auth security and UX` (Contains AI fluff)
+
+---
+
+## 2. PR Description Template
+
+```markdown
+## 📌 Motivation
+- [Briefly describe the issue solved, context, or feature request fulfilled]
+
+## 🛠️ Key Changes
+- [Key point 1: Modified module/file and rationale]
+- [Key point 2: Added logic or architectural improvement]
+- [Key point 3: Environment or dependency adjustments]
+
+## ⚠️ Impact & Breaking Changes
+- [Detail impacts on other modules, API contracts, or DB schemas. State "None" if inapplicable]
+
+## 🧪 Verification & Test Steps
+- [List automated tests executed, e.g., `npm test` or `dotnet test`]
+- [Manual verification steps and expected outcomes]
+```
+
+---
+
+## 3. Anti-Slop Conversion Table
+
+When drafting PR descriptions, rigorously filter out filler words according to the following mapping:
+
+| ❌ Fluff Phrase | ⭕ Clean Alternative | Explanation |
+| :--- | :--- | :--- |
+| It is worth noting that this PR refactors auth logic. | Refactor authorization logic to use unified middleware. | Delete throat-clearing openers; use direct action verbs. |
+| This PR aims to resolve a potential crash during login. | Fix crash during login caused by null User reference. | Omit "This PR aims to"; state goal and root cause directly. |
+| In summary, this change seamlessly boosts system performance. | Reduce DB queries, lowering API latency by 40ms. | Replace "seamlessly" with concrete metrics. |
+| Imagine a scenario where unhandled requests hit the server... | Add defensive 401 error handling for unauthenticated requests. | Remove hypothetical setups; state defensive logic clearly. |

package/skills/neo-pr/scripts/git-pr-extractor.py

@@ -0,0 +1,100 @@
+# /// script
+# dependencies = []
+# ///
+
+"""
+git-pr-extractor.py
+
+Non-interactive Git diff and commit extraction script.
+Given target_branch and source_branch, fetches Git logs, changed files, and diff summary,
+then outputs JSON formatted data to stdout.
+"""
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+
+def run_command(cmd, cwd=None):
+    result = subprocess.run(
+        cmd,
+        cwd=cwd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True
+    )
+    return result.returncode, result.stdout, result.stderr
+
+def main():
+    parser = argparse.ArgumentParser(description="Extract git diff and commit information for PR generation.")
+    parser.add_argument("--target-branch", default="main", help="Target base branch (e.g. main, develop)")
+    parser.add_argument("--source-branch", default="HEAD", help="Source feature branch (e.g. feature/auth, HEAD)")
+    parser.add_argument("--repo-path", default=".", help="Path to git repository")
+    parser.add_argument("--max-diff-lines", type=int, default=500, help="Maximum lines of diff to include")
+
+    args = parser.parse_args()
+    repo_path = os.path.abspath(args.repo_path)
+
+    # Verify if directory is inside a valid Git workspace
+    code, out, err = run_command(["git", "rev-parse", "--is-inside-work-tree"], cwd=repo_path)
+    if code != 0:
+        sys.stderr.write(f"Error: Path {repo_path} is not a valid git repository.\n{err}")
+        sys.exit(1)
+
+    # Retrieve current branch name for fallback reference
+    _, current_branch, _ = run_command(["git", "rev-parse", "--abbrev-ref", "HEAD"], cwd=repo_path)
+    current_branch = current_branch.strip()
+
+    source = args.source_branch
+    if source == "HEAD":
+        source_name = current_branch
+    else:
+        source_name = source
+
+    target = args.target_branch
+    rev_range = f"{target}..{source}"
+
+    # 1. Fetch Commit History
+    code, log_out, log_err = run_command(["git", "log", rev_range, "--oneline"], cwd=repo_path)
+    if code != 0:
+        sys.stderr.write(f"Error executing git log for range {rev_range}:\n{log_err}")
+        sys.exit(1)
+
+    commits = [line.strip() for line in log_out.strip().split("\n") if line.strip()]
+
+    # 2. Fetch git diff --stat Summary
+    _, stat_out, _ = run_command(["git", "diff", rev_range, "--stat"], cwd=repo_path)
+
+    # 3. Fetch List of Modified Files
+    _, name_status_out, _ = run_command(["git", "diff", rev_range, "--name-status"], cwd=repo_path)
+    changed_files = []
+    for line in name_status_out.strip().split("\n"):
+        if line.strip():
+            parts = line.strip().split(maxsplit=1)
+            if len(parts) == 2:
+                changed_files.append({"status": parts[0], "file": parts[1]})
+
+    # 4. Fetch Truncated Git Diff Output (Prevents Token Overhead)
+    _, diff_out, _ = run_command(["git", "diff", rev_range], cwd=repo_path)
+    diff_lines = diff_out.split("\n")
+    is_truncated = len(diff_lines) > args.max_diff_lines
+    short_diff = "\n".join(diff_lines[:args.max_diff_lines])
+
+    output_data = {
+        "repository_path": repo_path,
+        "target_branch": target,
+        "source_branch": source_name,
+        "commit_count": len(commits),
+        "commits": commits,
+        "stat_summary": stat_out.strip(),
+        "changed_files": changed_files,
+        "diff_snippet": short_diff,
+        "diff_truncated": is_truncated
+    }
+
+    # Output JSON string exclusively to stdout
+    print(json.dumps(output_data, ensure_ascii=False, indent=2))
+
+if __name__ == "__main__":
+    main()