Skip to content
Back to search

bundles-forge-dev

MarketplaceWorks with Claude CodeGitHub

An agentic skills framework & bundle-plugin engineering toolkit that works.

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/odradekai--bundles-forge/badge.svg)](/listings/odradekai--bundles-forge)

HTML

<a href="/listings/odradekai--bundles-forge"><img src="/api/listings/odradekai--bundles-forge/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

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

Install (Claude Code)

1. **Add the marketplace**:

   /plugin marketplace add OdradekAI/bundles-forge

2. **Install the plugin**:

   /plugin install bundles-forge@bundles-forge-dev

Or clone locally for development:

git clone https://github.com/OdradekAI/bundles-forge.git
cd bundles-forge

# Add your local marketplace
/plugin marketplace add ./

# Install the plugin
/plugin install bundles-forge@bundles-forge-dev

> Other platforms: see [Platform Support](#platform-support) below.

Path A: Build a New Bundle-Plugin

bundles-forge:blueprinting

This starts a structured interview to design your project — scope, platform targets, skill decomposition. When the design is ready, the agent automatically chains into `scaffolding` (project generation) and then `authoring` (SKILL.md writing).

Path B: Audit an Existing Project

cd your-bundle-plugin-project
bundles-forge:auditing

Runs a 10-category quality assessment with pattern-based security checks across 7 file categories.

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.

.claude-plugin/marketplace.json · Manifest · 22 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "bundles-forge-dev",
  3. "metadata": {
  4. "description": "Development marketplace for bundles-forge core skills library"
  5. },
  6. "owner": {
  7. "name": "Luiz",
  8. "email": "odradekai@outlook.com"
  9. },
  10. "plugins": [
  11. {
  12. "name": "bundles-forge",
  13. "description": "Bundle-plugin engineering toolkit: scaffolding, platform adaptation, version management, and skill lifecycle",
  14. "version": "1.8.7",
  15. "source": "./",
  16. "author": {
  17. "name": "Luiz",
  18. "email": "odradekai@outlook.com"
  19. }
  20. }
  21. ]
  22. }
README.md · README · 364 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Bundles Forge
  2. [中文](README.zh.md)
  3. A toolkit for building **bundle-plugins** — AI coding plugins organized around collaborative skill workflows — across Claude Code, Cursor, Codex, OpenCode, Gemini CLI, and OpenClaw.
  4. ## What is a Bundle-Plugin?
  5. A single skill (`SKILL.md`) does one thing — an AI agent discovers it by its `description` field and loads it on demand. A **bundle-plugin** takes this further: multiple skills reference each other and form a workflow, where one skill's output feeds the next.
  6. ```mermaid
  7. graph LR
  8. A["Skill A"] -->|output feeds| B["Skill B"]
  9. B -->|output feeds| C["Skill C"]
  10. C -->|validates| A
  11. ```
  12. bundles-forge itself is a bundle-plugin — `blueprinting` produces a design, `scaffolding` generates a project from it, `auditing` validates the result, and `optimizing` iterates on issues found.
  13. **If your plugin has 3+ skills that form a workflow, you're building a bundle-plugin.** This toolkit gives you scaffolding, quality gates, and multi-platform publishing for that pattern.
  14. ## Quick Start
  15. ### Install (Claude Code)
  16. 1. **Add the marketplace**:
  17. ```bash
  18. /plugin marketplace add OdradekAI/bundles-forge
  19. ```
  20. 2. **Install the plugin**:
  21. ```bash
  22. /plugin install bundles-forge@bundles-forge-dev
  23. ```
  24. Or clone locally for development:
  25. ```bash
  26. git clone https://github.com/OdradekAI/bundles-forge.git
  27. cd bundles-forge
  28. # Add your local marketplace
  29. /plugin marketplace add ./
  30. # Install the plugin
  31. /plugin install bundles-forge@bundles-forge-dev
  32. ```
  33. > Other platforms: see [Platform Support](#platform-support) below.
  34. ### Path A: Build a New Bundle-Plugin
  35. ```
  36. bundles-forge:blueprinting
  37. ```
  38. This starts a structured interview to design your project — scope, platform targets, skill decomposition. When the design is ready, the agent automatically chains into `scaffolding` (project generation) and then `authoring` (SKILL.md writing).
  39. ### Path B: Audit an Existing Project
  40. ```
  41. cd your-bundle-plugin-project
  42. bundles-forge:auditing
  43. ```
  44. Runs a 10-category quality assessment with pattern-based security checks across 7 file categories.
  45. ## Concepts
  46. | Concept | What it is |
  47. |---------|------------|
  48. | **Skill** | Atomic capability unit (`SKILL.md`) — discovered by description, loaded on demand |
  49. | **Plugin** | Packaging/distribution unit — bundles skills, agents, hooks, and more |
  50. | **Subagent** | Isolated AI assistant for delegated tasks with its own context window |
  51. | **Hook** | Shell/HTTP/LLM/Agent action that fires automatically on lifecycle events |
  52. | **MCP** | Open standard connecting Claude to external tools and data sources |
  53. > Full explanations, design decisions, and architecture diagrams → [Concepts Guide](docs/concepts-guide.md)
  54. ## Skills
  55. The 8 skills cover the full lifecycle of a bundle-plugin project, organized into two layers:
  56. - **Orchestrators** (`blueprinting`, `optimizing`, `releasing`) — diagnose, decide, and delegate. They chain multiple skills together to accomplish multi-step goals.
  57. - **Executors** (`scaffolding`, `authoring`, `auditing`, `testing`) — single-responsibility workers. They can be invoked directly by users or dispatched by orchestrators.
  58. ```mermaid
  59. flowchart LR
  60. Design["blueprinting"] --> Scaffold["scaffolding"]
  61. Design -->|"content authoring"| Write["authoring"]
  62. Design -->|"initial audit"| Audit["auditing"]
  63. Audit -->|issues| Optimize["optimizing"]
  64. Optimize -->|"delegate changes"| Write
  65. Optimize --> Audit
  66. Audit -->|pass| Test["testing"]
  67. Test -->|pass| Release["releasing"]
  68. ```
  69. | Phase | Skill | What It Does |
  70. |-------|-------|-------------|
  71. | Design | `blueprinting` | Three-phase interview (needs exploration → architecture design → design review) → design document → orchestrates the creation pipeline: scaffolding, authoring, workflow design, and initial audit. |
  72. | Scaffold | `scaffolding` | Generates project structure from design, adds or removes platform support — manifests, hooks, scripts, bootstrap skill, and per-platform files. |
  73. | Write | `authoring` | Guides SKILL.md and agents/*.md authoring — frontmatter, descriptions, instructions, content integration, and progressive disclosure via `references/`. |
  74. | Audit | `auditing` | 10-category quality assessment including pattern-based security checks across 7 file categories. |
  75. | Test | `testing` | Dynamic verification — local dev-marketplace install, hook smoke tests, component discovery, and cross-platform readiness checks. |
  76. | Optimize | `optimizing` | Engineering improvements — description triggering, token efficiency, workflow restructuring, adding skills to fill gaps, and feedback iteration. |
  77. | Release | `releasing` | Orchestrates the pre-release pipeline: version drift check, audit, testing, documentation consistency, change coherence review, version bump, CHANGELOG update, and publish guidance. |
  78. The bootstrap meta-skill `using-bundles-forge` provides a lightweight session prompt via hooks and full routing context on demand via the Skill tool.
  79. **Standalone use:** `authoring`, `auditing`, and `optimizing` can be invoked independently on any existing project without going through the full lifecycle.
  80. ### Guides
  81. Each skill has a companion guide in [`docs/`](docs/) with detailed usage, examples, and design rationale:
  82. | Guide | Covers |
  83. |-------|--------|
  84. | [Concepts Guide](docs/concepts-guide.md) | Core terminology, architecture diagrams, and design decisions |
  85. | [Blueprinting Guide](docs/blueprinting-guide.md) | Three-phase interview, dialogue strategy, design document format, decomposition patterns |
  86. | [Scaffolding Guide](docs/scaffolding-guide.md) | Project anatomy, platform adapters, template system |
  87. | [Authoring Guide](docs/authoring-guide.md) | SKILL.md writing patterns, progressive disclosure, agent authoring |
  88. | [Auditing Guide](docs/auditing-guide.md) | Checklists, report templates, CI integration |
  89. | [Optimizing Guide](docs/optimizing-guide.md) | Description tuning, token reduction, workflow restructuring |
  90. | [Releasing Guide](docs/releasing-guide.md) | Version management, CHANGELOG format, publishing workflow |
  91. ### Agents
  92. | Agent | Role |
  93. |-------|------|
  94. | `inspector` | Validates scaffolded project structure and platform adaptation |
  95. | `auditor` | Executes systematic quality audit with security scanning |
  96. | `evaluator` | Runs A/B skill evaluation for optimization and workflow chain verification for auditing (W10-W11) |
  97. ### Invoking Skills
  98. Skills are invoked **automatically** (the agent matches user intent to the skill's `description` field) or **explicitly** via `bundles-forge:<skill-name>` references — for example, `bundles-forge:auditing` or `bundles-forge:blueprinting`.
  99. ## Auditing
  100. Both `auditing` and `optimizing` accept local paths, GitHub URLs, and zip/tar.gz archives as input — the agent normalizes the target automatically.
  101. Four audit scopes for different levels of granularity — the agent auto-detects scope from the target path:
  102. | Scope | Invocation / Script | What It Checks |
  103. |-------|---------------------|----------------|
  104. | Full Project | `bundles-forge:auditing` or `bundles-forge audit-plugin` | 10 categories (structure, manifests, version sync, skill quality, cross-refs, workflow, hooks, testing, docs, security) |
  105. | Single Skill | `bundles-forge:auditing` on `skills/authoring` or `bundles-forge audit-skill` | 4 categories (structure, skill quality, cross-refs, security) |
  106. | Workflow | Explicit request or `bundles-forge audit-workflow` | 3 layers: static structure, semantic interface, behavioral verification (W1-W11) |
  107. | Security Only | `bundles-forge:auditing` (security-only mode) or `bundles-forge audit-security` | Pattern-based detection across 7 file categories (skill content, hook scripts, HTTP hooks, OpenCode plugins, agent prompts, bundled scripts, MCP configs) |
  108. ### Quick Start (Scripts)
  109. ```bash
  110. bundles-forge audit-plugin . # full project audit
  111. bundles-forge audit-skill skills/authoring # single skill audit
  112. bundles-forge audit-workflow . # workflow audit
  113. bundles-forge audit-workflow --focus-skills new-skill . # focused workflow audit
  114. bundles-forge audit-security . # security-only scan
  115. ```
  116. Via the agent, you can also audit remote projects:
  117. ```
  118. bundles-forge:auditing https://github.com/user/repo
  119. bundles-forge:auditing https://github.com/user/repo/tree/main/skills/my-skill
  120. ```
  121. Exit codes: `0` = pass, `1` = warnings, `2` = critical findings. All scripts accept `--json` for CI integration.
  122. **After the audit:** The audit report is purely diagnostic — it identifies and scores issues but does not prescribe next steps. The user or an orchestrating skill (e.g., `optimizing`, `releasing`) decides what to fix and how.
  123. > For detailed usage, checklists, report templates, and CI integration patterns, see [`docs/auditing-guide.md`](docs/auditing-guide.md).
  124. ## Architecture
  125. <details>
  126. <summary>Skill execution chains and internal routing</summary>
  127. > For concept explanations see [Concepts Guide](docs/concepts-guide.md). For per-skill details see guides in [`docs/`](docs/).
  128. ### Skill Execution
  129. Each skill is discovered by its description or invoked explicitly via `bundles-forge:<skill-name>`. The execution chains can be deep.
  130. ```mermaid
  131. flowchart LR
  132. subgraph skills [Entry-Point Skills]
  133. SK_BP["blueprinting"]
  134. SK_SF["scaffolding"]
  135. SK_AU["auditing"]
  136. SK_OP["optimizing"]
  137. SK_RE["releasing"]
  138. end
  139. SK_BP -->|"design approved"| scaffolding
  140. SK_BP -->|"content authoring"| authoring
  141. SK_BP -->|"initial audit"| SK_AU
  142. SK_AU -->|"issues found"| SK_OP
  143. SK_OP -->|"delegate changes"| authoring
  144. SK_OP -->|"verify fixes"| SK_AU
  145. SK_RE -->|"pre-release check"| SK_AU
  146. SK_RE -->|"fix quality"| SK_OP
  147. ```
  148. #### `bundles-forge:blueprinting` — Plan a new bundle-plugin
  149. > Full guide: [`docs/blueprinting-guide.md`](docs/blueprinting-guide.md)
  150. **When to use:** Starting a new project, splitting a monolithic skill into multiple skills, or composing third-party skills into a bundle.
  151. ```
  152. User invokes bundles-forge:blueprinting
  153. → blueprinting: context exploration (scan existing files/skills)
  154. → blueprinting: Phase 1 — needs exploration (problem, users, capabilities, flow)
  155. → blueprinting: Phase 2 — architecture design (complexity, platforms, skill decomposition, workflow)
  156. → blueprinting: Phase 3 — generate design document + self-review
  157. → User approves design document (HARD-GATE)
  158. → Scaffold: invoke scaffolding — generate project structure, manifests, hooks, scripts
  159. → inspector agent validates scaffold (if subagents available)
  160. → Author Content: invoke authoring — guide SKILL.md and agents/*.md content (with design context)
  161. → Wire Workflow: blueprinting wires cross-references, integration sections
  162. → Run Audit: invoke auditing — initial quality check
  163. ```
  164. #### `bundles-forge:scaffolding` — Generate or adapt project structure
  165. > Full guide: [`docs/scaffolding-guide.md`](docs/scaffolding-guide.md)
  166. **When to use:** Adding platform support to an existing project, removing a platform, or generating a new project directly (without going through blueprinting first).
  167. ```
  168. User invokes bundles-forge:scaffolding
  169. → scaffolding: detect context (new project vs existing project)
  170. → New project: ask mode preference (intelligent/custom), generate structure
  171. → Existing project:
  172. → Add/remove platform: generate adapter files, update .version-bump.json, hooks, README
  173. → Add/remove optional components (MCP servers, CLI executables, LSP, userConfig, output-styles)
  174. → inspector agent validates changes (if subagents available)
  175. ```
  176. #### `bundles-forge:auditing` — Quality assessment
  177. > Full guide: [`docs/auditing-guide.md`](docs/auditing-guide.md)
  178. **When to use:** Reviewing a project before release, after significant changes, or when scanning a third-party skill for security risks.
  179. ```
  180. User invokes bundles-forge:auditing
  181. → auditing: detect scope (full project vs single skill vs workflow)
  182. → Full project: 10 categories (structure, manifests, version sync,
  183. quality, cross-refs, workflow, hooks, testing, docs, security)
  184. → auditor agent runs checklist (if subagents available)
  185. → Scripts: bundles-forge audit-plugin, audit-workflow, audit-security, audit-skill
  186. → Single skill: 4 categories (structure, quality, cross-refs, security)
  187. → Workflow: 3 layers (static structure, semantic interface, behavioral)
  188. → Score + report with Critical / Warning / Info findings
  189. → Report delivered to calling context (user or orchestrating skill) for action
  190. ```
  191. #### `bundles-forge:auditing` (security-only mode) — Security-focused audit
  192. **When to use:** Quick security-only check. Maps to the `auditing` skill in security-only mode — runs only Category 10 (the 7-surface security scan: skill content, hook scripts, HTTP hooks, OpenCode plugins, agent prompts, bundled scripts, MCP configs), skipping Categories 1-8.
  193. #### `bundles-forge:optimizing` — Engineering improvements
  194. > Full guide: [`docs/optimizing-guide.md`](docs/optimizing-guide.md)
  195. **When to use:** Improving description triggering accuracy, reducing token usage, fixing workflow chain gaps, adding skills to fill gaps, restructuring workflows, or iterating on user feedback about a specific skill.
  196. ```
  197. User invokes bundles-forge:optimizing
  198. → optimizing: detect scope (project vs single skill)
  199. → Project scope: 6 optimization targets
  200. (descriptions, tokens, workflow chains,
  201. security, restructuring, optional components)
  202. → Skill scope: targeted optimization + feedback iteration
  203. → Description A/B test:
  204. → 2x evaluator agents in parallel (if subagents available)
  205. → Compare reports → pick winner
  206. → Verify fixes via auditing
  207. ```
  208. #### `bundles-forge:releasing` — Version bump and publish
  209. > Full guide: [`docs/releasing-guide.md`](docs/releasing-guide.md)
  210. **When to use:** Preparing a release — version drift check, quality gate, documentation consistency, version bump, CHANGELOG update, and publishing guidance.
  211. ```
  212. User invokes bundles-forge:releasing
  213. → releasing: verify prerequisites (clean working tree, branch check)
  214. → Pre-flight checks
  215. → bundles-forge bump-version --check (version drift)
  216. → auditing (full quality + security)
  217. → bundles-forge audit-docs (documentation consistency)
  218. → Address critical findings (block release until resolved)
  219. → Documentation sync (change coherence review + doc updates)
  220. → bundles-forge bump-version <new-version> (update all manifests)
  221. → Update CHANGELOG.md and README.md
  222. → Final verification (--check + --audit + bundles-forge audit-docs)
  223. → Commit, tag, push, gh release create
  224. ```
  225. </details>
  226. ## Platform Support
  227. ### Cursor
  228. Search for `bundles-forge` in the Cursor plugin marketplace, or use `/add-plugin bundles-forge`.
  229. ### Codex
  230. See [`.codex/INSTALL.md`](.codex/INSTALL.md)
  231. ### OpenCode
  232. See [`.opencode/INSTALL.md`](.opencode/INSTALL.md)
  233. ### Gemini CLI
  234. ```bash
  235. gemini extensions install https://github.com/OdradekAI/bundles-forge.git
  236. ```
  237. ### OpenClaw
  238. From ClawHub:
  239. ```bash
  240. openclaw bundles install clawhub:bundles-forge
  241. ```
  242. From a local clone:
  243. ```bash
  244. openclaw plugins install ./bundles-forge
  245. ```
  246. Verify with `openclaw plugins inspect bundles-forge` — should show `Format: bundle`.
  247. ## Tips for Long Sessions
  248. Skills, audit reports, and script output accumulate in the conversation context over a long session. If you notice the agent slowing down or losing track of earlier context:
  249. - **Start a fresh session** for each major lifecycle phase (blueprinting, authoring, auditing)
  250. - **Invoke skills explicitly** (`bundles-forge:auditing`, `bundles-forge:optimizing`) to re-anchor the agent on the current task
  251. - **Prefer script output over inline checks** — `bundles-forge audit-plugin .` produces a compact summary instead of the agent reasoning through each check
  252. ## Prerequisites
  253. - **Python 3.9+** — required for auditing scripts and version management tools
  254. - **`python` or `python3` in PATH** — the `bundles-forge` CLI dispatcher probes both via `find_python()`. On systems where only `python3` is available, create an alias or symlink:
  255. - **macOS/Linux:** `sudo ln -s $(which python3) /usr/local/bin/python`
  256. - **Windows:** Python installer includes `python` by default; verify with `python --version`
  257. ## Contributing
  258. Contributions welcome. Please follow the existing code style and ensure all platform manifests stay in sync using `bundles-forge bump-version --check` and `bundles-forge checklists --check`.
  259. ## License
  260. Apache-2.0

Ratings and comments

Sign in to rate this skill.

Sign in

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