Skip to content
Back to search

idd-skills

Antigravity plugin for autonomous Issue-Driven Development (IDD) — from GitHub Issues to specs, git worktree implementation, and Pull Requests.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 19 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/sawarame/idd-skills with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/sawarame/idd-skills'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sawarame--idd-skills/badge.svg)](/listings/sawarame--idd-skills)

HTML

<a href="/listings/sawarame--idd-skills"><img src="/api/listings/sawarame--idd-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

By cloning this repository into the `~/.gemini/config/plugins` directory, it is automatically recognized and enabled as a global **Antigravity** plugin.

# Create the plugins directory if it does not exist
mkdir -p ~/.gemini/config/plugins

# Navigate to the directory and clone the repository
cd ~/.gemini/config/plugins
git clone https://github.com/sawarame/idd-skills.git

If you prefer to clone via SSH, run the following commands:

cd ~/.gemini/config/plugins
git clone git@github.com:sawarame/idd-skills.git

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 163 lines
  1. # idd-skills
  2. An issue-driven development (IDD) plugin compatible with **Google Antigravity**.
  3. ## `idd-implement` Skill Documentation
  4. An autonomous, non-interactive skill that starts from a GitHub Issue number and executes the full workflow end-to-end: **reviewing requirements and open questions → posting a specification/technical requirements comment (or exiting after posting a clarification comment) → implementing and verifying in a `git worktree` → creating a Pull Request → returning to the original branch**.
  5. Using the bundled wrapper script [`scripts/gh-as-bot.mjs`](./skills/idd-implement/scripts/gh-as-bot.mjs), the skill posts Issue comments and creates Pull Requests **as a dedicated GitHub App (`<app-name>[bot]`) when `~/.config/github-app/.env` is present**, or **as the locally authenticated GitHub user** when it is not configured.
  6. ---
  7. ## Behavior (Authentication Switching Rules)
  8. | Condition | Authentication Identity Used |
  9. | :--- | :--- |
  10. | `~/.config/github-app/.env` **exists** | Installation Access Token of the GitHub App (`<app-name>[bot]`) specified in `.env` |
  11. | `~/.config/github-app/.env` **does not exist** | The user currently logged into the local `gh` CLI (`gh auth status`) |
  12. > [!IMPORTANT]
  13. > **Preventing Unintended Posts from a Personal Account**
  14. > If `~/.config/github-app/.env` exists and there are missing configuration values, a missing `.pem` file, or an API authentication error, `gh-as-bot.mjs` will fail with an error rather than silently falling back to your personal account.
  15. ---
  16. ## Prerequisites
  17. - **Node.js** (v18 or later recommended; uses built-in modules only, so `npm install` is not required)
  18. - **GitHub CLI (`gh`)**
  19. - Must be authenticated via `gh auth login` if not using a GitHub App
  20. - **Git** (with `git worktree` support)
  21. ---
  22. ## Installation
  23. By cloning this repository into the `~/.gemini/config/plugins` directory, it is automatically recognized and enabled as a global **Antigravity** plugin.
  24. ```bash
  25. # Create the plugins directory if it does not exist
  26. mkdir -p ~/.gemini/config/plugins
  27. # Navigate to the directory and clone the repository
  28. cd ~/.gemini/config/plugins
  29. git clone https://github.com/sawarame/idd-skills.git
  30. ```
  31. If you prefer to clone via SSH, run the following commands:
  32. ```bash
  33. cd ~/.gemini/config/plugins
  34. git clone git@github.com:sawarame/idd-skills.git
  35. ```
  36. ---
  37. ## Creating a GitHub App (Bot)
  38. If you want AI-generated Issue comments and Pull Requests to be separated from your personal account and posted with a `[bot]` badge, create a dedicated GitHub App by following these steps:
  39. 1. Log in to GitHub, click your profile icon in the top-right corner, and navigate to **Settings** → **Developer settings** (at the bottom of the left sidebar) → **GitHub Apps** → **New GitHub App**.
  40. 2. Fill in the basic information:
  41. - **GitHub App name**: Enter any unique name (this name will be displayed as `<app-name>[bot]`, e.g., `yourname-ai-agent`).
  42. - **Homepage URL** (required): Enter a valid `https://...` URL (no running web server is required; your GitHub profile `https://github.com/<username>` or a repository URL is sufficient).
  43. - **Identifying and authorizing users (Callback URL, etc.)**: Leave all fields **blank**.
  44. 3. Under the **Webhook** section, **uncheck Active** (since the script runs locally and does not use a webhook receiver server).
  45. 4. Under **Permissions** → **Repository permissions**, configure the following permissions:
  46. - **Issues**: `Read and write` (required to view Issues and post comments)
  47. - **Pull requests**: `Read and write` (required to create and update PRs)
  48. - **Contents**: `Read and write` (required if `git push` is performed with a Bot token in the future; `Read-only` is sufficient if pushing with standard local `git` credentials)
  49. - **Metadata**: Automatically set to `Read-only`.
  50. 5. Under **Where can this GitHub App be installed?**, select **Only on this account**, then click **Create GitHub App**.
  51. 6. On the created app's settings page, note the **App ID** (numeric) shown in the **About** section.
  52. 7. Scroll down to the **Private keys** section on the same page, click **Generate a private key**, and download the `.pem` file.
  53. 8. Open **Install App** in the left sidebar, click **Install** for your account, and install it on the target repositories (or **All repositories**).
  54. ---
  55. ## Setting Up the `.pem` File and `.env`
  56. ### 1. Move the `.pem` File to a Secure Location
  57. Do not store the private key (`.pem`) inside a Git repository or a cloud-synced folder (such as iCloud). Place it under `~/.config/github-app/` with restricted permissions.
  58. ```bash
  59. mkdir -p ~/.config/github-app
  60. chmod 700 ~/.config/github-app
  61. # Move the downloaded .pem file and restrict read/write access to the owner only
  62. mv ~/Downloads/<downloaded-filename>.pem ~/.config/github-app/<app-name>.pem
  63. chmod 600 ~/.config/github-app/<app-name>.pem
  64. ```
  65. ### 2. Create `~/.config/github-app/.env`
  66. Create `~/.config/github-app/.env` with the following contents and also set its permissions to `600`.
  67. ```dotenv
  68. GITHUB_APP_ID=123456
  69. GITHUB_APP_PRIVATE_KEY_PATH=~/.config/github-app/<app-name>.pem
  70. ```
  71. ```bash
  72. chmod 600 ~/.config/github-app/.env
  73. ```
  74. #### Configurable Variables
  75. | Variable Name | Required | Description |
  76. | :--- | :---: | :--- |
  77. | `GITHUB_APP_ID` | Required | The **App ID** (numeric) from your GitHub App settings page |
  78. | `GITHUB_APP_PRIVATE_KEY_PATH` | Required | Path to the `.pem` file. Supports `~`, `$HOME`, `${HOME}`, or a path relative to `.env` |
  79. | `GITHUB_APP_INSTALLATION_ID` | Optional | Specify only if you want to pin a specific Installation ID (auto-detected from the target repository when omitted) |
  80. | `GITHUB_APP_ENV_FILE` | Optional | When set as an environment variable, specifies an alternative `.env` file path instead of the default `~/.config/github-app/.env` |
  81. ---
  82. ## Verification
  83. You can verify the setup by running the following read-only commands inside a repository directory where the GitHub App is installed (these commands do not modify Issues or PRs).
  84. ### Verify Bot Authentication
  85. ```bash
  86. # Succeeds if a number representing accessible repositories is returned
  87. node ~/.gemini/config/plugins/idd-skills/skills/idd-implement/scripts/gh-as-bot.mjs api /installation/repositories --jq '.repositories | length'
  88. # Test fetching a specific Issue
  89. node ~/.gemini/config/plugins/idd-skills/skills/idd-implement/scripts/gh-as-bot.mjs issue view <issue-number> --json number,title
  90. ```
  91. > [!NOTE]
  92. > Calling `api /user` with a Bot's Installation Access Token returns `HTTP 403: Resource not accessible by integration`. This is expected behavior confirming authentication as a GitHub App (Installation Token) rather than a personal user.
  93. ### Verify Fallback When `.env` Is Absent
  94. ```bash
  95. # Temporarily pointing to a non-existent path displays the locally logged-in gh username
  96. GITHUB_APP_ENV_FILE=/tmp/nonexistent-gh-bot.env \
  97. node ~/.gemini/config/plugins/idd-skills/skills/idd-implement/scripts/gh-as-bot.mjs api /user --jq .login
  98. ```
  99. ---
  100. ## Security Design and Operational Notes
  101. - **Keeping Private Keys and Tokens Out of AI Context**
  102. `gh-as-bot.mjs` reads `.env` and `.pem` internally and passes the acquired Installation Access Token to the `gh` child process strictly in memory via the `GH_TOKEN` environment variable (it never caches tokens to disk or prints keys/tokens to stdout). [SKILL.md](./skills/idd-implement/SKILL.md) also prohibits AI agents from directly reading `.env` or `.pem` files.
  103. - **Authentication During `git push`**
  104. Bot authentication applies to GitHub API operations performed via the `gh` CLI (viewing Issues, posting comments, creating PRs). `git push` runs using your normal local Git credentials (SSH / HTTPS).
  105. *Note: Having the Bot create the PR also lets you review and approve the PR using your personal GitHub account.*
  106. ---
  107. ## Troubleshooting
  108. - **`Failed to retrieve GitHub App installation information for repository owner/repo` (`HTTP 404`)**
  109. - The GitHub App is not installed on the target repository. Add the repository from **Install App** in your GitHub App settings.
  110. - **`Resource not accessible by integration` (`HTTP 403`)**
  111. - The GitHub App may be missing `Issues: Read and write` or `Pull requests: Read and write` under **Repository permissions**. After updating permissions, you may need to approve the updated permissions on the installation page in GitHub (**Accept new permissions**).
  112. - **Comments or PRs are still posted under your personal account**
  113. - Check that `~/.config/github-app/.env` has the exact path and filename.
  114. - Check whether the agent called `gh` directly or used GitHub MCP tools instead of `gh-as-bot.mjs` ([SKILL.md](./skills/idd-implement/SKILL.md) specifies prioritizing `gh-as-bot.mjs`).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.