agent-toolbox 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,139 @@
+# Changelog
+
+All notable changes to the agent-toolbox CLI will be documented in this file.
+
+## [0.2.0] - 12026-03-10
+
+### Bug Fixes
+- Correct README path typo and fix pre-commit hook configuration (#9)
+
+
+### CI/CD
+- *(security)* Integrate Cisco Skill Scanner for automated skill security vetting (#8)
+- *(security)* Add verbose, incremental scanning, and monthly report archiving to skill-scanner (#11)
+- *(security)* Tune skill-scanner models and verbose dispatch handling (#12)
+- *(security)* Resolve skill-scanner verbose input merge markers (#13)
+- Add ESLint and Prettier checks to CI and release pipelines (#20)
+- *(scanner)* Enable VirusTotal unknown-file upload (#24)
+- *(scanner)* Output markdown reports on PR scans and remove push trigger (#25)
+- *(scanner)* Add push trigger with lightweight scan and PR concurrency (#29)
+
+
+### Documentation
+- Expand Why section with security vetting rationale and update package metadata (#3)
+- Add security policy and update README Contributing section (#5)
+- *(security)* Replace double hyphens with em dashes for proper rendering (#6)
+- *(skill)* Refine catalog-porter references and add SPDX license guidance (#10)
+- Lowercase docs/ filenames and update all references (#15)
+- Update AGENTS.md hierarchy for ESLint, Prettier, and Lefthook (#18)
+- Add known issues tracking document (#21)
+- *(cli)* Add dual-runtime architecture reference (#23)
+- *(security)* March 12026 security scan report & catalog hardening (#14)
+- *(readme)* Overhaul README and add CONTRIBUTING.md (#28)
+
+
+### Features
+- *(cli)* Add list, find, remove, check, update commands (#19)
+- *(cli)* Add dual-runtime build pipeline for npx and bunx support (#22)
+
+
+### Miscellaneous
+- V0.2.0 prep — branch protection, zod v4, npm package trim (#1)
+- Update Buy Me a Coffee username in FUNDING.yml (#2)
+- Rename project and release docs (#16)
+- Set up ESLint, Prettier, and Lefthook (#17)
+- *(github)* Add pull request template (#26)
+
+
+## [0.1.0] - 12026-02-28
+
+### Bug Fixes
+- Correct find-skills LICENSE copyright holder to Vercel, Inc.
+- Align skill frontmatter domains with consolidated taxonomy
+- *(ci)* Ignore volatile timestamp in drift detection
+
+
+### Build
+- Bootstrap Bun-first TypeScript toolchain
+
+
+### CI/CD
+- Add GitHub Actions CI/CD workflow
+
+
+### Documentation
+- Add AGENTS.md project knowledge base
+- Add license notice for git-master (Sustainable Use License 1.0)
+- Strengthen generic checklist and templates in docs-writer
+- Add reusable templates resource to docs-writer workflow
+- Add license notices for docs-writer (MIT + Apache 2.0 attribution)
+- Restructure root license with third-party component clause
+- Add license notice for github-triage (Sustainable Use License 1.0)
+- Add catalog taxonomy and selective installation architecture
+- Add n8n-derived catalog skills to README
+- Restructure README tables and add listing policy to AGENTS.md
+- Add hierarchical AGENTS.md for dev tooling and catalog directories
+- *(license)* Clarify SUL governance in all catalog NOTICE.md files
+- *(readme)* Add ported and external skill entries
+- Add openclaw skill entries and reference
+- *(AGENTS)* Add catalog curation scope policy
+- *(readme)* Add 33-js-concepts skill entries and reference
+- Update README and catalog metadata for awesome-llm-apps batch
+- Add dify skills and reference to README
+- Center README header
+- *(readme)* Add vercel/streamdown to references table
+- Add provenance classification guide
+- Codify ported skill body integrity convention
+- Add hierarchical AGENTS.md knowledge base via init-deep
+- Restructure documentation
+- Use bunx/npx install UX in README examples
+
+
+### Features
+- Enhance git-master with advanced workflow playbooks
+- Add first two skills from n8n
+- Add content-design and issue-analysis skills from n8n
+- Add create-pr skill from n8n (generalized)
+- Add docs-writer synthesized skill from multiple upstream sources
+- *(taxonomy)* Add developer-tooling, communications, generative-art subdomains
+- *(schemas)* Add Zod schemas for catalog and target types
+- *(cli)* Add validate and build-index commands
+- *(generators)* Add shared interface and copy utilities
+- *(generators)* Add Claude Code and OpenCode generators
+- *(generators)* Add Cursor, Codex, and Gemini generators
+- *(cli)* Add build-target command
+- *(install)* Add selective install engine
+- *(cli)* Add unified entrypoint with subcommand routing
+- *(release)* Add release infrastructure with bumpp, git-cliff, and GitHub Actions
+- *(cli)* Add runtime catalog provider with ETag-based freshness check
+
+
+### Miscellaneous
+- Create .gitignore
+- Add upstream git-master skill baseline
+- Add create-pr skill from n8n-io/n8n
+- Add github-triage skill from oh-my-opencode
+- Add skill-creator and mcp-builder skills from anthropics/skills
+- Update LICENSE copyright to Holocene Era year notation
+- Add find-skills skill from vercel-labs/skills
+- Add 5 skills from wshobson/agents
+- Add update-docs skill from vercel/next.js
+- Add consolidated docs-writer skill with profile references
+- Remove update-docs skill (superseded by docs-writer)
+- Add doc-coauthoring skill from anthropics/skills
+- Add docs-changelog skill from google-gemini/gemini-cli
+- Sync dev tooling create-pr skill with generalized catalog version
+- *(license)* Switch to SUL 1.0 and clarify attribution structure
+- Add frontmatter migration script
+- *(scripts)* Add provenance audit and sync tooling
+
+
+### Refactoring
+- Make docs-writer self-contained and remove gemini profile
+- Remove source-repo-specific assumptions from profiles
+- Consolidate taxonomy by merging testing into devops and adding disambiguation rules
+
+
+### Testing
+- Add unit and integration test suite
+

package/LICENSE.md

@@ -0,0 +1,81 @@
+# License
+
+Portions of this software are licensed as follows:
+
+- Content of branches other than the main branch are not licensed.
+- Certain third-party components incorporated into the agent-toolbox Software may retain their original license terms where explicitly indicated by a NOTICE.md file accompanying that component. All other content is governed by the Sustainable Use License below.
+- Content outside of the above mentioned files or restrictions is available under the "Sustainable Use License" as defined below.
+
+## Sustainable Use License
+
+Version 1.0
+
+### Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+### Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license
+to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject
+to the limitations below.
+
+### Limitations
+
+You may use or modify the software only for your own internal business purposes or for non-commercial or
+personal use. You may distribute the software or provide it to others only if you do so free of charge for
+non-commercial purposes. You may not alter, remove, or obscure any licensing, copyright, or other notices of
+the licensor in the software. Any use of the licensor’s trademarks is subject to applicable law.
+
+### Patents
+
+The licensor grants you a license, under any patent claims the licensor can license, or becomes able to
+license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case
+subject to the limitations and conditions in this license. This license does not cover any patent claims that
+you cause to be infringed by modifications or additions to the software. If you or your company make any
+written claim that the software infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company makes such a claim, your patent
+license ends immediately for work on behalf of your company.
+
+### Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these
+terms. If you modify the software, you must include in any modified copies of the software a prominent notice
+stating that you have modified the software.
+
+### No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+### Termination
+
+If you use the software in violation of these terms, such use is not licensed, and your license will
+automatically terminate. If the licensor provides you with a notice of your violation, and you cease all
+violation of this license no later than 30 days after you receive that notice, your license will be reinstated
+retroactively. However, if you violate these terms after such reinstatement, any additional violation of these
+terms will cause your license to terminate automatically and permanently.
+
+### No Liability
+
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will
+not be liable to you for any damages arising out of these terms or the use or nature of the software, under
+any kind of legal claim.
+
+### Definitions
+
+The “licensor” is the entity offering these terms.
+
+The “software” is the software the licensor makes available under these terms, including any portion of it.
+
+“You” refers to the individual or entity agreeing to these terms.
+
+“Your company” is any legal entity, sole proprietorship, or other kind of organization that you work for, plus
+all organizations that have control over, are under the control of, or are under common control with that
+organization. Control means ownership of substantially all the assets of an entity, or the power to direct its
+management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+“Your license” is the license granted to you for the software under these terms.
+
+“Use” means anything you do with the software requiring your license.
+
+“Trademark” means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,277 @@
+<div align="center">
+
+# agent-toolbox
+
+[![SUL-1.0 license](https://img.shields.io/badge/license-SUL%201.0-97ca00)](LICENSE.md)
+[![Release model](https://img.shields.io/badge/release_model-SemVer%20CLI%20%2B%20Rolling%20Catalog-0097a7)](./docs/release.md)
+[![GitHub issues](https://img.shields.io/badge/issue_tracking-GitHub-blue.svg)](https://github.com/snu-hanaro/static-fire-toolkit/issues)
+[![Cisco AI Defense](https://img.shields.io/badge/Secured%20by-Cisco%20AI%20Defense-049fd9?logo=cisco&logoColor=white)](https://github.com/cisco-ai-defense)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/yunseo-kim/agent-toolbox)
+
+[![CI](https://github.com/yunseo-kim/agent-toolbox/actions/workflows/ci.yml/badge.svg)](https://github.com/yunseo-kim/agent-toolbox/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/yunseo-kim/agent-toolbox/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/yunseo-kim/agent-toolbox/actions/workflows/github-code-scanning/codeql)
+[![Skill Security Scan](https://github.com/yunseo-kim/agent-toolbox/actions/workflows/skill-scanner.yml/badge.svg)](https://github.com/yunseo-kim/agent-toolbox/actions/workflows/skill-scanner.yml)
+
+Secure infrastructure for the **AI agent skill ecosystem**.
+
+A curated, security-vetted registry of agent skills that works across  
+**Claude Code, Codex, Gemini CLI, Cursor, OpenCode, and more.**
+
+[![Sponsor](https://img.shields.io/badge/Sponsor-yunseo--kim-EA4AAA?style=for-the-badge&logo=github-sponsors&logoColor=white)](https://github.com/sponsors/yunseo-kim)
+
+<a href="https://www.buymeacoffee.com/yunseokim" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
+
+</div>
+
+## What is agent-toolbox?
+
+AI coding assistants increasingly rely on **agent skills, plugins, hooks, and MCP servers**.
+
+But the ecosystem has two major problems:
+
+1. **Fragmentation** — standards like [Agent Skills](https://agentskills.io) define a common format, but don't guarantee that the content itself is tool-neutral
+2. **Security risks** — agent skills form a new software supply chain
+
+Recent research highlights the scale of the issue:
+
+- [Snyk found **13.4% of ~4,000 scanned agent skills contained critical security issues**](<(https://github.com/snyk/agent-scan/blob/main/.github/reports/skills-report.pdf)>)
+  - documented attacks include prompt injection, credential theft, and malware distribution
+- [1Password **discovered the top-downloaded skill on ClawHub was a multi-stage infostealer**](https://1password.com/blog/from-magic-to-malware-how-openclaws-agent-skills-become-an-attack-surface) — the "Twitter" skill embedded a fake "required dependency" that led users through a 5-stage delivery chain ending in a macOS binary with Gatekeeper bypass; [VirusTotal confirmed](https://www.virustotal.com/gui/file/30f97ae88f8861eeadeb54854d47078724e52e2ef36dd847180663b7f5763168) the binary as infostealing malware targeting browser sessions, credentials, developer tokens, and SSH keys
+  - **staged delivery**: fake prerequisite → staging page → obfuscated command → second-stage script → binary execution with quarantine removal
+  - **coordinated campaign**: [subsequent reporting](https://cyberinsider.com/341-openclaw-skills-distribute-macos-malware-via-clickfix-instructions/) revealed hundreds of skills distributing macOS malware via ClickFix-style instructions — not an isolated upload
+- [Cisco's AI Threat Research team **proved the #1 most-downloaded skill on OpenClaw's registry was functional malware**](https://blogs.cisco.com/ai/personal-ai-agents-like-openclaw-are-a-security-nightmare) — their [Skill Scanner](https://github.com/cisco-ai-defense/skill-scanner) found **9 security findings (2 critical, 5 high severity)** in the "What Would Elon Do?" skill:
+  - **silent data exfiltration**: the skill executed `curl` commands sending user data to an attacker-controlled server without any user notification
+  - **prompt injection**: forced the AI assistant to bypass its own safety guidelines and execute commands without user consent
+  - **command injection**: embedded bash commands executed through the skill's workflow
+  - **tool poisoning**: malicious payloads concealed within the skill file itself
+  - the malicious skill's popularity had been artificially inflated to rank #1 — demonstrating that **bad actors can manufacture trust in unvetted registries**
+
+In many ecosystems, a `SKILL.md` file is effectively **an installer for arbitrary logic**.
+
+**agent-toolbox treats agent skills as a new software supply chain.**
+
+It provides a **curated, security-scanned catalog of agent components**,  
+with cross-tool compatibility and automated provenance tracking.
+
+## What You Get
+
+You're browsing plugin marketplaces. Saving "awesome" lists from the community.  
+You see impressive demos everywhere — but don't want to risk navigating a minefield of prompt injections, credential theft, and malware to boost your productivity.
+
+**agent-toolbox takes care of the hard part. Just remember this: `bunx agent-toolbox install`. Done.**
+
+agent-toolbox provides:
+
+- **110+ curated agent skills** across multiple domains
+- **cross-tool compatibility** for major AI coding assistants
+- **automated security scanning**
+- **provenance tracking** for upstream sources
+- **flexible installation filters**
+
+Think of it as:
+
+> **Homebrew + Sigstore + npm audit for AI agent skills**
+
+## Use Cases
+
+agent-toolbox can be used to:
+
+- install curated agent skills for **Claude Code, Codex, Cursor, or Gemini CLI**
+- share a **standardized skill catalog across teams**
+- **audit third-party skills** before installing them
+- maintain **secure agent tooling infrastructure**
+- experiment with **cross-tool agent ecosystems**
+
+## Getting Started
+
+### Install Skills
+
+```bash
+# Install all skills for a target
+bunx agent-toolbox install --target claude-code
+
+# Filter by domain
+bunx agent-toolbox install --target gemini --domain devops
+
+# Filter by subdomain
+bunx agent-toolbox install --target gemini --domain devops --subdomain ci-cd
+
+# Use a curated preset
+bunx agent-toolbox install --target cursor --preset devops-essentials
+
+# Install specific skills
+bunx agent-toolbox install --target claude-code --skill git-master --skill docs-writer
+
+# Filter by framework or tag
+bunx agent-toolbox install --target codex --framework nextjs
+bunx agent-toolbox install --target gemini --tag yaml
+
+# Preview what would be installed
+bunx agent-toolbox install --target gemini --domain devops --dry-run
+```
+
+> [!TIP]
+> **npm users:** Replace `bunx` with `npx`.
+
+> [!NOTE]
+> All filters compose with AND logic. Default (no filters) installs everything.
+
+## Browse the Catalog
+
+The catalog currently contains **110+ skills across 10 domains**.
+
+Browse by domain:  
+**[View the full catalog →](catalog/README.md)**
+
+Skills are curated from leading open-source projects and adapted  
+for **cross-tool compatibility**.
+
+## Supported Targets
+
+| Target          | Artifact Format                  | Status      |
+| --------------- | -------------------------------- | ----------- |
+| **Claude Code** | `.claude/` skills + plugins      | Implemented |
+| **OpenCode**    | `skills/` with SKILL.md          | Implemented |
+| **Gemini CLI**  | `gemini-extension.json` + skills | Implemented |
+| **Cursor**      | `.cursor/` compatible artifacts  | Implemented |
+| **Codex**       | Agent skill directories          | Implemented |
+
+## Architecture
+
+```
+agent-toolbox/
+├── catalog/                          # Neutral source-of-truth
+│   ├── skills/                       # Flat — one dir per skill, taxonomy via frontmatter
+│   ├── agents/
+│   ├── commands/
+│   ├── hooks/
+│   ├── mcp/
+│   ├── lsp/
+│   └── metadata/                     # Taxonomy, presets, and generated index
+│       ├── taxonomy.yaml             # Controlled vocabulary (domains + subdomains)
+│       ├── presets.yaml              # Curated install bundles
+│       ├── upstream-sources.yaml     # Ported/adapted skill upstream mappings
+│       ├── skill-index.json          # Auto-generated aggregated skill metadata
+│       └── skill-index.toon          # Auto-generated TOON format for LLM consumption
+├── src/                              # Bun-first TS toolchain
+│   ├── catalog/                      # Skill scanning, validation, index building
+│   ├── cli/                          # install/build/validate entrypoints
+│   ├── generators/                   # claude-code / opencode / cursor / codex / gemini
+│   ├── install/                      # Selective install engine + filter composition
+│   ├── mappers/                      # Tool/event/model mapping layers
+│   └── schemas/                      # Zod schemas for catalog + targets + install
+├── templates/                        # Target-specific render templates
+├── dist/
+│   ├── targets/                      # Runtime artifacts per tool
+│   │   ├── claude-code/
+│   │   ├── opencode/
+│   │   ├── cursor/
+│   │   ├── codex/
+│   │   └── gemini/
+│   └── marketplace/                  # Catalog artifacts (Claude-specific)
+└── tests/
+    ├── unit/                         # Schema, taxonomy, frontmatter, scanner, filter
+    ├── integration/                  # Generator and install pipeline tests
+    └── matrix/                       # Cross-target verification
+```
+
+### Workflow
+
+1. **Catalog** — neutral SKILL.md definitions with frontmatter metadata (`domain`, `tags`, `frameworks`, `author`, `lastUpdated`, `provenance`).
+2. **Generators** — transform catalog into tool-specific artifacts
+3. **Install engine** — deploy skills with flexible filtering
+
+## Security
+
+Every skill in the catalog is automatically scanned using [**Cisco Skill Scanner**](https://github.com/cisco-ai-defense/skill-scanner) with a [custom strict-based policy](docs/skill-scanner-policy.md).
+
+The security pipeline combines multiple detection engines:
+
+- **Static analysis** — YAML + YARA pattern matching, bytecode verification, shell pipeline taint analysis
+- **Behavioral analysis** — AST-based dataflow tracking from sources to sinks across multiple files
+- **LLM semantic analysis** — OpenAI gpt-5.4 evaluates code intent against Cisco's AITech threat taxonomy
+- **Meta-analysis** — Second-pass false positive filtering with cross-finding correlation
+- **VirusTotal** — Hash-based binary malware scanning
+
+Security findings are published through **GitHub Code Scanning**.
+
+Monthly full-scan reports are archived in [docs/security-reports/](docs/security-reports/).
+
+For full details, see [SECURITY.md](SECURITY.md).
+
+> [!IMPORTANT]
+> To report vulnerabilities:
+>
+> - [GitHub Security Advisories](https://github.com/yunseo-kim/agent-toolbox/security/advisories/new)
+> - email [oss-security@yunseo.kim](mailto:oss-security@yunseo.kim).
+
+## Support
+
+> [!NOTE]
+> If you find **agent-toolbox** useful, consider supporting the project.
+>
+> Maintaining agent-toolbox requires ongoing work including catalog review, security analysis, and cross-tool compatibility maintenance.
+>
+> Parts of the security pipeline currently rely on personally funded infrastructure, including:
+>
+> - **OpenAI API** usage for LLM-based security analysis
+> - Rate-limited **VirusTotal public API** for malware detection
+>
+> Support helps sustain these security capabilities and expand the scanning infrastructure.
+
+### Individual Support
+
+**GitHub Sponsors:**  
+[![Sponsor](https://img.shields.io/badge/Sponsor-yunseo--kim-EA4AAA?style=for-the-badge&logo=github-sponsors&logoColor=white)](https://github.com/sponsors/yunseo-kim)
+
+**Buy Me a Coffee:**  
+<a href="https://www.buymeacoffee.com/yunseokim" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
+
+### Corporate Sponsorship
+
+Organizations building or relying on AI coding assistants such as Claude Code, Codex, Cursor, or Gemini CLI may consider sponsoring the project.
+
+Corporate sponsorship helps sustain:
+
+- security scanning infrastructure
+- catalog curation and review
+- cross-tool compatibility maintenance
+- long-term ecosystem development
+
+> [!TIP]
+> Corporate sponsors may be listed in the README.
+
+## Sponsors
+
+<!-- corporate sponsor logos will appear here -->
+
+## Contributing
+
+Contributions are welcome. Please read [`CONTRIBUTING.md`](CONTRIBUTING.md) for guidelines on setting up a development environment, submitting changes, and adding catalog skills.
+
+## License
+
+**agent-toolbox** is released under the [Sustainable Use License 1.0](LICENSE.md).
+
+> [!NOTE]
+> The project is free to use for individuals, research, and open-source development. The Sustainable Use License is designed to enable broad community use while supporting the long-term sustainability of the project and its maintenance.
+
+### Commercial Licensing
+
+**agent-toolbox** aims to serve as secure infrastructure for the emerging AI agent skill ecosystem.
+
+Organizations integrating or distributing **agent-toolbox** as part of a commercial AI product or hosted platform may require a **commercial license**.
+
+Examples include:
+
+- bundling agent-toolbox within an AI coding assistant
+- integrating the catalog into a proprietary developer tool
+- operating a hosted service built on agent-toolbox infrastructure
+
+Commercial licenses provide:
+
+- rights for commercial distribution
+- proprietary product integration
+- optional ecosystem partnership recognition
+
+If your organization is interested in integrating **agent-toolbox** into a commercial product or platform, please reach out to **contact@yunseo.kim**.

package/dist/cli/launcher.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+/**
+ * Launcher wrapper for dual-runtime support.
+ *
+ * This is the `bin` entry point for the npm package. It auto-detects
+ * the invoking package manager and routes to the appropriate runtime:
+ *
+ *   npx agent-toolbox     → Node.js (runs main.js directly)
+ *   bunx agent-toolbox    → Node.js detects bunx → re-execs with Bun
+ *   bunx --bun agent-toolbox → Bun directly (shebang bypassed)
+ *
+ * This file is plain JavaScript (not compiled) — it must run on any
+ * Node.js >= 18 without transpilation.
+ */
+
+const isBunx = (process.env.npm_config_user_agent || "").includes("bun/");
+
+if (typeof globalThis.Bun === "undefined" && isBunx) {
+  // bunx invoked us but the #!/usr/bin/env node shebang forced Node.js.
+  // Re-execute the compiled main.js under Bun for native performance.
+  const { spawnSync } = await import("node:child_process");
+  const { fileURLToPath } = await import("node:url");
+  const main = fileURLToPath(new URL("./main.js", import.meta.url));
+  const { status } = spawnSync("bun", [main, ...process.argv.slice(2)], {
+    stdio: "inherit",
+  });
+  process.exit(status ?? 0);
+} else {
+  // Node.js (npx) or Bun (bunx --bun) — run main.js in-process.
+  await import("./main.js");
+}