@kurokeita/add-skill 1.12.0 → 1.14.0

package/dist/skills/git-branch/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: git-branch
+description: This skill should be used when the user asks to "create a branch", "branch naming", "branch strategy", or "follow conventional branch". Provides guidelines for version control branching strategies and rules.
+version: 1.0.0
+---
+
+# Git Branch
+
+Guide for managing version control branching strategies following the Conventional Branch specification.
+
+## When to Use This Skill
+
+- Creating new feature, bugfix, or maintenance branches
+- Ensuring branch names follow project standards
+- Managing branch lifecycle and organization
+- Integrating issue tracker IDs into branch names
+
+## Branching Strategy
+
+Follow the [Conventional Branch](https://conventional-branch.github.io/) specification for consistent and descriptive branch naming.
+
+### Structure
+
+The branch structure follows a categorized format:
+`<type>/<description>`
+
+### Types (`<type>`)
+
+- `main`: The primary development branch (e.g., `main`, `master`, or `develop`).
+- `feat/`: For new features (e.g., `feat/add-login-page`).
+- `fix/`: For bug fixes (e.g., `fix/header-bug`).
+- `hotfix/`: For urgent production fixes (e.g., `hotfix/security-patch`).
+- `release/`: For preparing a new release (e.g., `release/v1.2.0`).
+- `chore/`: For non-code tasks like dependencies or documentation updates (e.g., `chore/update-dependencies`).
+
+### Naming Rules
+
+- **Character Set**: Use lowercase alphanumerics (`a-z`, `0-9`), hyphens (`-`), and dots (`.`).
+- **Separators**: Use hyphens to separate words in the description. Dots are permitted in `release/` branches for versioning.
+- **Restrictions**:
+  - Avoid special characters, underscores, or spaces.
+  - No consecutive hyphens or dots (e.g., avoid `new--login`).
+  - No leading or trailing hyphens/dots in the description.
+- **Conciseness**: Keep names descriptive yet brief.
+- **Ticket Integration**: Include project management ticket numbers if applicable (e.g., `feat/issue-123-new-login`).
+
+### Workflow
+
+1. Start from the main integration branch.
+2. Ensure the local branch is up-to-date: `git pull origin main`.
+3. Create the new branch: `git checkout -b <type>/<description>`.
+
+## Additional Resources
+
+### Reference Files
+
+For detailed patterns and advanced git workflows, consult:
+
+- **`references/branching-workflows.md`** - Advanced branching and merging strategies.

package/dist/skills/git-branch/references/branching-workflows.md

@@ -0,0 +1,63 @@
+# Advanced Branching and Merging Strategies
+
+Choosing the right branching strategy is crucial for team collaboration and continuous delivery.
+
+## Gitflow Workflow
+
+Gitflow is a legacy Git workflow that was first published and made popular by Vincent Driessen. It's often used for projects that have a scheduled release cycle.
+
+- `main` branch stores the official release history.
+- `develop` branch serves as an integration branch for features.
+- `feature/*` branches are used for developing new features.
+- `release/*` branches support preparation of a new production release.
+- `hotfix/*` branches are used to quickly patch production releases.
+
+## GitHub Flow
+
+GitHub Flow is a lightweight, branch-based workflow that supports teams and projects where deployments happen regularly.
+
+- Anything in the `main` branch is deployable.
+- To work on something new, create a descriptive branch off of `main`.
+- Commit to that branch locally and regularly push your work to the same named branch on the server.
+- When you need feedback or help, or you think the branch is ready for merging, open a pull request.
+- After someone else has reviewed and signed off on the feature, you can merge it into `main`.
+- Once it is merged and pushed to `main`, you can and should deploy immediately.
+
+## Trunk-Based Development
+
+A version control management strategy where developers merge small, frequent updates to a core “trunk” or main branch.
+
+- High frequency of commits.
+- Small PRs.
+- Continuous Integration.
+- Feature flags are often used to hide work-in-progress.
+
+## Merging vs Rebasing
+
+### Merging
+
+`git merge` is a "non-destructive" operation. The existing branches are not changed in any way. This avoids all of the potential pitfalls of rebasing.
+
+```bash
+git checkout feature/abc
+git merge main
+```
+
+### Rebasing
+
+`git rebase` moves the entire feature branch to begin on the tip of the `main` branch, effectively incorporating all of the new commits in `main`. It re-writes the project history by creating brand new commits for each commit in the original branch.
+
+```bash
+git checkout feature/abc
+git rebase main
+```
+
+**Golden Rule of Rebasing**: Never use it on public branches.
+
+## Conflict Resolution
+
+1. Identify the conflict: `git status` will show unmerged paths.
+2. Open the files and look for `<<<<<<<`, `=======`, `>>>>>>>`.
+3. Decide which changes to keep.
+4. Stage the resolved files: `git add <file>`.
+5. Complete the merge or rebase: `git commit` or `git rebase --continue`.

package/dist/skills/git-clean/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: git-clean
+description: This skill should be used when the user asks to "clean the repository", "remove stale branches", "clear old stashes", "manage git hygiene", or "scan for redundant worktrees". Uses the @kurokeita/git-clean-up tool to audit and safely remove unused Git resources.
+version: 1.0.0
+---
+
+# Git Clean Skill
+
+Maintain repository hygiene by scanning for and removing stale branches, forgotten stashes, and redundant worktrees using the `@kurokeita/git-clean-up` tool.
+
+## When to Use This Skill
+
+- Auditing the repository for stale or merged branches.
+- Cleaning up old stashes or redundant Git worktrees.
+- Improving local performance by removing unneeded Git objects.
+- Automating repository hygiene tasks.
+
+## Workflow
+
+Follow this procedure to safely clean the repository:
+
+### 1. Detect package runner
+
+Determine whether to use `pnpx` or `npx` by checking if `pnpm` is installed. Always prioritize `pnpx`.
+
+```bash
+# Check for pnpm
+pnpm --version
+```
+
+- If `pnpm` is available: Use `pnpx @kurokeita/git-clean-up`
+- If `pnpm` is NOT available: Use `npx @kurokeita/git-clean-up`
+
+### 2. Audit findings
+
+Run an initial scan using the `--json` flag to identify hygiene issues without making any changes. This enables precise analysis of the findings.
+
+```bash
+<runner> @kurokeita/git-clean-up scan --json
+```
+
+### 3. Present report
+
+Summarize the findings for the user, categorized by:
+
+- **Branches**: Merged, squash-merged, or branches without upstreams.
+- **Stashes**: Old stashes or stale WIPs.
+- **Worktrees**: Missing paths or detached HEADs.
+
+### 4. Solicit confirmation
+
+Present the findings to the user and ask which items or categories they would like to clean. Do NOT proceed to deletion without explicit user approval.
+
+### 5. Preview cleanup (Optional but Recommended)
+
+If the user wants to see exactly what will be deleted for a specific selection, run the clean command without the `--apply` flag.
+
+```bash
+# Preview all deletions
+<runner> @kurokeita/git-clean-up clean --all
+
+# Preview specific categories
+<runner> @kurokeita/git-clean-up clean --include branches,stashes
+```
+
+### 6. Execute cleanup
+
+After receiving confirmation, run the clean command with the `--apply` flag.
+
+```bash
+# Clean everything confirmed
+<runner> @kurokeita/git-clean-up clean --apply --all
+
+# Clean specific categories
+<runner> @kurokeita/git-clean-up clean --apply --include branches
+```
+
+## Safety Considerations
+
+- **Protected Branches**: The tool automatically protects `main`, `master`, `develop`, and `dev`. Do not attempt to override these protections unless explicitly instructed.
+- **Active Branches**: Branches checked out in other worktrees are skipped by default.
+- **Verification**: Always verify the list of findings with the user before applying deletions.
+
+## Additional Resources
+
+### Reference Files
+
+- **`references/tool-options.md`**: Detailed CLI options and configuration settings for `git-clean-up`.
+
+### Example Configurations
+
+- **`examples/config.json`**: Sample `.git-clean-up.json` for repository-specific hygiene policies.

package/dist/skills/git-clean/examples/config.json

@@ -0,0 +1,7 @@
+{
+	"protectedBranches": ["release/*", "hotfix/*", "production"],
+	"includeCategories": ["branches", "stashes", "worktrees"],
+	"stashAgeDays": 21,
+	"defaultTargetBranch": "origin/main",
+	"branchInactiveDays": 60
+}

package/dist/skills/git-clean/references/tool-options.md

@@ -0,0 +1,59 @@
+# Git Clean Up Tool Options
+
+Detailed reference for CLI options and configuration settings for the `@kurokeita/git-clean-up` tool.
+
+## Core Commands
+
+### `scan`
+
+Audits the repository and lists hygiene issues without modifying any resources.
+
+**Options:**
+
+- `--json`: Output findings in JSON format for programmatic parsing.
+- `--include <categories>`: Comma-separated list of categories to scan (branches, stashes, worktrees).
+- `--target <branch>`: Specify the primary integration branch (default: `main` or `master`).
+- `--age-days <number>`: Filter stashes or inactive branches older than X days.
+
+### `clean`
+
+Previews or applies deletions based on hygiene audit results.
+
+**Options:**
+
+- `--apply`: Actually execute the deletion of selected items. Without this flag, the command only provides a preview.
+- `--all`: Select all identified hygiene issues for cleanup.
+- `--include <categories>`: Limit cleanup to specific categories (e.g., `--include branches`).
+- `--force`: Force removal even if safety checks fail (use with extreme caution).
+
+## Configuration File
+
+Behavior can be customized using a `.git-clean-up.json` file in the repository root or a global configuration at `~/.git-clean-up.json`.
+
+### Example Configuration
+
+```json
+{
+  "protectedBranches": [
+    "release/*",
+    "hotfix/*",
+    "production"
+  ],
+  "includeCategories": [
+    "branches",
+    "stashes",
+    "worktrees"
+  ],
+  "stashAgeDays": 14,
+  "defaultTargetBranch": "origin/develop",
+  "branchInactiveDays": 30
+}
+```
+
+## Policy Enforcement (CI Mode)
+
+The tool can be used in CI pipelines to enforce repository hygiene.
+
+- `--fail-on <level>`: Exit with a non-zero code if findings of a certain risk level (low, medium, high) are found.
+- `--max-findings <number>`: Fail if the total number of hygiene issues exceeds the specified threshold.
+- `--summary`: Output a high-level summary of findings, ideal for build logs.

package/dist/skills/git-commit/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: git-commit
+description: This skill should be used when the user asks to "commit changes", "commit message", or "follow conventional commits". Provides guidelines for Conventional Commits specification and commit message formatting.
+version: 1.0.0
+---
+
+# Git Commit
+
+Guide for managing version control commit message formatting following the Conventional Commits specification.
+
+## When to Use This Skill
+
+- Formatting commit messages to follow project standards
+- Learning the Conventional Commits specification
+- Ensuring consistency across the repository's history
+
+## Conventional Commits
+
+Format commit messages according to the [Conventional Commits](https://www.conventionalcommits.org/) specification to enable automated changelog generation and easier history browsing.
+
+### Structure
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Types
+
+- `feat`: A new feature
+- `fix`: A bug fix
+- `docs`: Documentation only changes
+- `style`: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.)
+- `refactor`: A code change that neither fixes a bug nor adds a feature
+- `perf`: A code change that improves performance
+- `test`: Adding missing tests or correcting existing tests
+- `build`: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
+- `ci`: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
+- `chore`: Other changes that don't modify src or test files
+- `revert`: Reverts a previous commit
+
+### Guidelines
+
+- **Description**: Use the imperative, present tense (e.g., "add", not "added" or "adds").
+- **Case**: The description should be in lower-case or sentence-case.
+- **Scope**: Use a scope to provide additional contextual information (e.g., `feat(auth): add login validation`).
+- **Body**: Use the body to explain the "what" and "why" of the change, not the "how".
+- **Footer**: Use the footer to reference issues (e.g., `Closes #123`) or breaking changes.
+
+## Additional Resources
+
+### Reference Files
+
+For detailed patterns and advanced git workflows, consult:
+
+- **`references/conventional-commits.md`** - Detailed Conventional Commits specification.
+
+### Example Files
+
+Working examples in `examples/`:
+
+- **`commit-messages.txt`** - Examples of well-formatted commit messages.

package/dist/skills/git-commit/examples/commit-messages.txt

@@ -0,0 +1,34 @@
+# Example Commit Messages
+
+## Features
+- `feat(ui): add progress bar component`
+- `feat(auth): implement oauth2 login with google`
+- `feat!: change default api version to v2`
+
+## Bug Fixes
+- `fix(parser): handle empty input string gracefully`
+- `fix: resolve race condition in database connection pool`
+- `fix(styles): fix padding issues on mobile devices`
+
+## Documentation
+- `docs: update readme with installation instructions`
+- `docs(api): document the new /user/profile endpoint`
+- `docs: add contributing guide`
+
+## Refactoring
+- `refactor(core): simplify the request handling logic`
+- `refactor: move utility functions to a separate module`
+- `refactor(tests): reduce duplication in integration tests`
+
+## Performance
+- `perf(image): optimize image loading speed using lazy-loading`
+- `perf: add caching layer for frequently accessed data`
+
+## Tests
+- `test(auth): add unit tests for jwt validation`
+- `test: increase coverage for the math module`
+
+## Chore
+- `chore: update dependencies`
+- `chore(deps): bump vite from 4.0 to 5.0`
+- `chore: remove unused log statements`

package/dist/skills/git-commit/references/conventional-commits.md

@@ -0,0 +1,85 @@
+# Conventional Commits Specification
+
+The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of.
+
+## The Specification
+
+The commit message should be structured as follows:
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Type
+
+The type is a short string that describes the category of the change. Common types include:
+
+- `feat`: (feature)
+- `fix`: (bug fix)
+- `docs`: (documentation)
+- `style`: (formatting, missing semi-colons, etc; no code change)
+- `refactor`: (refactoring production code)
+- `test`: (adding missing tests, refactoring tests; no production code change)
+- `chore`: (updating grunt tasks etc; no production code change)
+
+### Scope
+
+A scope MAY be provided after a type. A scope MUST consist of a noun describing a section of the codebase surrounded by parenthesis, e.g., `fix(parser):`
+
+### Description
+
+The description contains a succinct description of the change:
+
+- use the imperative, present tense: "change" not "changed" nor "changes"
+- don't capitalize the first letter
+- no dot (.) at the end
+
+### Body
+
+A longer commit body MAY be provided after the short description, providing additional contextual information about the code changes. The body MUST begin one blank line after the description.
+
+### Footer
+
+One or more footers MAY be provided one blank line after the body. Each footer MUST consist of a word token, followed by either a `:<space>` or `<space>#` separator, followed by a string value (this is inspired by the git trailer convention).
+
+### Breaking Changes
+
+A breaking change MUST be indicated by an `!` after the type/scope, or as a footer entry starting with `BREAKING CHANGE:`.
+
+## Examples
+
+### Commit message with description and breaking change footer
+
+```
+feat: allow provided config object to extend other configs
+
+BREAKING CHANGE: `extends` key in config file is now used for extending other config files
+```
+
+### Commit message with ! to draw attention to breaking change
+
+```
+feat!: send an email to the customer when a product is shipped
+```
+
+### Commit message with scope and ! to draw attention to breaking change
+
+```
+chore(api)!: drop support for Node 6
+```
+
+### Commit message with multi-paragraph body and multiple footers
+
+```
+fix: prevent racing of requests
+
+Introduce a request id and a reference to latest request. All
+rest responses are checked against the current id before update.
+
+Reviewers: adrian, jdoe
+Fixes #123
+```

package/dist/skills/git-pr/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: git-pr
+description: This skill should be used when the user asks to "create a pull request", "open a PR", "prepare a pull request", or "review a PR description". Provides guidelines for effective pull request management and industry-standard templates.
+version: 1.0.0
+---
+
+# Git Pull Request
+
+Guide for creating and managing clear and informative pull requests to facilitate effective code review and collaboration.
+
+## When to Use This Skill
+
+- Preparing and creating pull requests
+- Writing pull request descriptions
+- Ensuring pull requests meet quality standards before submission
+- Managing the PR lifecycle and reviewer feedback
+
+## Pull Request Management
+
+Create clear and informative pull requests to ensure that reviewers can understand the impact and context of your changes.
+
+### PR Creation Process
+
+1. **Push your branch**: `git push origin <branch-name>`.
+2. **Open the PR**: Use the GitHub CLI or web interface.
+3. **Title**: Use the Conventional Commits format for the title (e.g., `feat(ui): add dashboard widgets`).
+4. **Description**: Use a template (if available) to describe:
+    - What changes were made.
+    - Why they were made.
+    - How they were tested.
+    - Any breaking changes or new dependencies.
+
+### Best Practices
+
+- **Keep it focused**: One PR per logical change. Avoid "mega-PRs".
+- **Self-review**: Review your own changes before asking others.
+- **Link issues**: Use keywords like `Fixes #123` or `Closes #123` in the description.
+- **Update regularly**: Rebase or merge from the main branch if the PR becomes stale.
+
+## Additional Resources
+
+### Reference Files
+
+For detailed patterns and industry-standard analysis, consult:
+
+- **`references/pr-best-practices.md`** - Analysis of PR patterns from top repositories.
+
+### Example Files
+
+Working examples in `examples/`:
+
+- **`pr-description-template.md`** - A standard, industry-standard PR description template.

package/dist/skills/git-pr/examples/pr-description-template.md

@@ -0,0 +1,40 @@
+## Summary
+<!-- Explain the **motivation** for making this change. What existing problem does the pull request solve? -->
+
+## Related Issue
+<!-- Link to the issue this PR addresses (e.g., Fixes #123, Closes #456) -->
+Fixes #
+
+## Type of Change
+<!-- Please delete options that are not relevant -->
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+- [ ] Refactor (code change that neither fixes a bug nor adds a feature)
+
+## How did you test this change?
+<!-- 
+Please describe the tests that you ran to verify your changes. 
+Provide instructions so we can reproduce. 
+Please also list any relevant details for your test configuration.
+-->
+- [ ] Test Case A: ...
+- [ ] Test Case B: ...
+
+### Screenshots (if applicable)
+<!-- Add images to show visual changes -->
+
+## Checklist
+
+- [ ] I have read the [CONTRIBUTING](CONTRIBUTING.md) document.
+- [ ] My code follows the code style of this project.
+- [ ] I have performed a self-review of my own code.
+- [ ] I have commented my code, particularly in hard-to-understand areas.
+- [ ] I have made corresponding changes to the documentation.
+- [ ] My changes generate no new warnings.
+- [ ] I have added tests that prove my fix is effective or that my feature works.
+- [ ] New and existing unit tests pass locally with my changes.
+
+## Special notes for your reviewer
+<!-- Any specific areas you want the reviewer to focus on? -->

package/dist/skills/git-pr/references/pr-best-practices.md

@@ -0,0 +1,66 @@
+# Pull Request Description Best Practices
+
+A well-crafted pull request (PR) description is essential for effective code review, maintaining project history, and ensuring that changes meet quality standards.
+
+## Core Components
+
+The most effective PR templates across major open-source repositories (like React, VS Code, and Kubernetes) share these core components:
+
+### 1. Summary & Motivation
+
+Explain **what** you changed and **why** you changed it.
+
+- What problem does this PR solve?
+- What is the context for this change?
+- Are there any architectural decisions or trade-offs made?
+
+### 2. Related Issues
+
+Always link to the issue(s) being addressed. Use keywords that GitHub recognizes to automatically close issues when the PR is merged:
+
+- `Fixes #123`
+
+- `Closes #123`
+
+- `Resolves #123`
+
+### 3. Type of Change
+
+Categorize the PR to help maintainers quickly understand its impact:
+
+- **Bug Fix**: Non-breaking change that fixes an issue.
+
+- **New Feature**: Non-breaking change that adds functionality.
+
+- **Breaking Change**: Fix or feature that would cause existing functionality to change.
+- **Documentation**: Changes to documentation only.
+- **Refactor**: Code change that neither fixes a bug nor adds a feature.
+
+### 4. Test Plan (Verification)
+
+Describe how you verified your changes. This is the most critical section for reviewers.
+
+- **Automated Tests**: Mention new or existing tests that cover the changes.
+- **Manual Testing**: List the steps taken to manually verify the behavior.
+- **Screenshots/Gifs**: Provide visual evidence for UI/UX changes.
+
+### 5. Checklist
+
+A set of mandatory steps the contributor must confirm:
+
+- [ ] My code follows the project's style guidelines.
+- [ ] I have performed a self-review of my code.
+- [ ] I have added tests that cover my changes.
+- [ ] All new and existing tests passed.
+- [ ] I have updated the documentation accordingly.
+
+### 6. Special Notes for Reviewers
+
+Use this section to highlight specific areas where you need feedback or to explain complex logic that might be hard to follow.
+
+## Best Practices
+
+- **Keep it focused**: One logical change per PR. Small PRs are easier to review and less likely to introduce bugs.
+- **Write for the future**: Your PR description will be part of the repository's history. Write it so that someone reading it a year from now can understand the context.
+- **Be concise but thorough**: Avoid "fluff," but don't leave out critical information.
+- **Update the description**: If the PR evolves during the review process, update the description to reflect the final state of the changes.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kurokeita/add-skill",
-	"version": "1.12.0",
+	"version": "1.14.0",
 	"description": "CLI to install AI agent skills to various platforms",
 	"type": "module",
 	"bin": {