agent-skill-manager 1.0.0

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,59 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainers via
+[GitHub Issues](https://github.com/luongnv89/skill-manager/issues).
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

package/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing to skill-manager
+
+Thanks for your interest in contributing! This guide will help you get started.
+
+## Getting Started
+
+### Prerequisites
+
+- [Bun](https://bun.sh) >= 1.0.0
+- [Git](https://git-scm.com/)
+
+### Development Setup
+
+```bash
+git clone https://github.com/luongnv89/skill-manager.git
+cd skill-manager
+bun install
+bun run start        # Launch the TUI
+```
+
+### Running Tests
+
+```bash
+bun test             # Run all tests
+bun run typecheck    # Type-check without emitting
+```
+
+## How to Contribute
+
+### Reporting Bugs
+
+Open a [bug report](https://github.com/luongnv89/skill-manager/issues/new?template=bug_report.md) with:
+
+- Steps to reproduce
+- Expected vs. actual behavior
+- Your environment (OS, Bun version)
+
+### Suggesting Features
+
+Open a [feature request](https://github.com/luongnv89/skill-manager/issues/new?template=feature_request.md) describing the problem and your proposed solution.
+
+### Submitting Code
+
+1. Fork the repository
+2. Create a feature branch from `main`:
+   ```bash
+   git checkout -b feat/your-feature
+   ```
+3. Make your changes
+4. Run tests and type-checking:
+   ```bash
+   bun test
+   bun run typecheck
+   ```
+5. Commit using [Conventional Commits](https://www.conventionalcommits.org/):
+   ```
+   feat: add new provider type
+   fix: handle missing config directory
+   docs: update keyboard shortcuts table
+   ```
+6. Push and open a Pull Request against `main`
+
+### Branching Strategy
+
+- `main` — stable, release-ready code
+- `feat/*` — new features
+- `fix/*` — bug fixes
+- `docs/*` — documentation changes
+
+### Code Style
+
+- TypeScript strict mode (`tsconfig.json` has `"strict": true`)
+- Pre-commit hooks handle formatting via Prettier
+- Keep functions focused and files small
+- Follow existing patterns in the codebase
+
+### Testing
+
+- Tests live alongside source files (`*.test.ts`)
+- Use the Bun test runner (`bun test`)
+- Add tests for new logic, especially in `scanner.ts`, `config.ts`, and `uninstaller.ts`
+
+## Pull Request Process
+
+1. Fill out the PR template
+2. Ensure CI passes (type-check + tests)
+3. Keep PRs focused — one feature or fix per PR
+4. A maintainer will review and merge
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 luongnv89
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/logo/logo-full.svg" />
+    <source media="(prefers-color-scheme: light)" srcset="assets/logo/logo-black.svg" />
+    <img src="assets/logo/logo-full.svg" alt="skill-manager" width="480" />
+  </picture>
+</p>
+
+<p align="center">
+  <em>The universal skill manager for AI coding agents.</em>
+</p>
+
+<p align="center">
+  <a href="#install">Install</a> &middot;
+  <a href="#usage">Usage</a> &middot;
+  <a href="#configuration">Configuration</a> &middot;
+  <a href="CONTRIBUTING.md">Contributing</a> &middot;
+  <a href="LICENSE">License</a>
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License" /></a>
+  <a href="https://bun.sh"><img src="https://img.shields.io/badge/runtime-Bun%20%E2%89%A5%201.0-black.svg" alt="Bun" /></a>
+</p>
+
+---
+
+**skill-manager** is an interactive terminal UI for managing installed skills across AI coding agents — [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), [OpenClaw](https://github.com/openclaw), and more. Built with [OpenTUI](https://github.com/nicholasgasior/opentui) and [Bun](https://bun.sh).
+
+## Features
+
+- **Multi-agent support** — Manage skills for Claude Code, Codex, OpenClaw, and custom agent tools from one TUI
+- **Configurable providers** — Define which agent tool directories to scan via `~/.config/skill-manager/config.json`
+- **Global & project scopes** — Filter skills by global (`~/.<tool>/skills/`) or project-level (`./<tool>/skills/`)
+- **Real-time search** — Filter skills by name, description, or provider
+- **Sort** — By name, version, or location
+- **Detailed skill view** — Metadata from SKILL.md frontmatter including provider, path, symlink info
+- **Safe uninstall** — Confirmation dialog, removes skill directories, rule files, and AGENTS.md blocks
+- **In-TUI config editor** — Toggle providers on/off, or open config in `$EDITOR`
+
+## Install
+
+**Prerequisites:** [Bun](https://bun.sh) >= 1.0.0
+
+```bash
+bun install -g agent-skill-manager
+```
+
+Or run directly from source:
+
+```bash
+git clone https://github.com/luongnv89/skill-manager.git
+cd skill-manager
+bun install
+bun run start
+```
+
+## Usage
+
+```bash
+skill-manager              # Launch the interactive TUI
+skill-manager --help       # Show help
+skill-manager --version    # Show version
+```
+
+## Keyboard Shortcuts
+
+| Key            | Action                                |
+| -------------- | ------------------------------------- |
+| `↑/↓` or `j/k` | Navigate skill list                   |
+| `Enter`        | View skill details                    |
+| `d`            | Uninstall selected skill              |
+| `/`            | Search / filter skills                |
+| `Esc`          | Back / clear filter / close dialog    |
+| `Tab`          | Cycle scope: Global → Project → Both  |
+| `s`            | Cycle sort: Name → Version → Location |
+| `r`            | Refresh / rescan skills               |
+| `c`            | Open configuration                    |
+| `q`            | Quit                                  |
+| `?`            | Toggle help overlay                   |
+
+## Configuration
+
+On first run, a config file is created at `~/.config/skill-manager/config.json` with default providers:
+
+```json
+{
+  "version": 1,
+  "providers": [
+    {
+      "name": "claude",
+      "label": "Claude Code",
+      "global": "~/.claude/skills",
+      "project": ".claude/skills",
+      "enabled": true
+    },
+    {
+      "name": "codex",
+      "label": "Codex",
+      "global": "~/.codex/skills",
+      "project": ".codex/skills",
+      "enabled": true
+    },
+    {
+      "name": "openclaw",
+      "label": "OpenClaw",
+      "global": "~/.openclaw/skills",
+      "project": ".openclaw/skills",
+      "enabled": true
+    },
+    {
+      "name": "agents",
+      "label": "Agents",
+      "global": "~/.agents/skills",
+      "project": ".agents/skills",
+      "enabled": true
+    }
+  ],
+  "customPaths": [],
+  "preferences": {
+    "defaultScope": "both",
+    "defaultSort": "name"
+  }
+}
+```
+
+- **Add providers** — Add new entries to the `providers` array for any agent tool
+- **Custom paths** — Add arbitrary directories via `customPaths`
+- **Disable providers** — Set `enabled: false` to skip scanning a provider
+- **Preferences** — Set default scope and sort order
+
+You can also toggle providers on/off directly in the TUI by pressing `c`.
+
+## Supported Agent Tools
+
+| Tool             | Global Path           | Project Path        |
+| ---------------- | --------------------- | ------------------- |
+| Claude Code      | `~/.claude/skills/`   | `.claude/skills/`   |
+| Codex            | `~/.codex/skills/`    | `.codex/skills/`    |
+| OpenClaw         | `~/.openclaw/skills/` | `.openclaw/skills/` |
+| Agents (generic) | `~/.agents/skills/`   | `.agents/skills/`   |
+
+Additional tools can be added via the config file.
+
+## Project Structure
+
+```
+skill-manager/
+├── bin/                    # CLI entry point
+│   └── skill-manager.ts
+├── src/
+│   ├── index.ts            # App bootstrap & keyboard handling
+│   ├── config.ts           # Config loading & saving
+│   ├── scanner.ts          # Skill directory scanning & filtering
+│   ├── uninstaller.ts      # Safe skill removal logic
+│   ├── utils/
+│   │   ├── types.ts        # Shared TypeScript types
+│   │   ├── colors.ts       # TUI color palette
+│   │   └── frontmatter.ts  # SKILL.md frontmatter parser
+│   └── views/
+│       ├── dashboard.ts    # Main dashboard layout
+│       ├── skill-list.ts   # Scrollable skill list
+│       ├── skill-detail.ts # Skill detail overlay
+│       ├── confirm.ts      # Uninstall confirmation dialog
+│       ├── config.ts       # In-TUI config editor
+│       └── help.ts         # Help overlay
+├── docs/                   # Extended documentation
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Tech Stack
+
+- **Runtime:** [Bun](https://bun.sh) >= 1.0.0
+- **Language:** TypeScript (ESNext, strict mode)
+- **TUI Framework:** [OpenTUI](https://github.com/nicholasgasior/opentui)
+- **Testing:** Bun test runner
+- **CI:** GitHub Actions + pre-commit hooks
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+[MIT](LICENSE) — see the [LICENSE](LICENSE) file for details.

package/RELEASE_NOTES.md

@@ -0,0 +1,31 @@
+## v1.0.0 — 2025-03-11
+
+Initial release of **skill-manager** — the universal skill manager for AI coding agents.
+
+### Features
+
+- Interactive TUI dashboard built with OpenTUI and Bun
+- Multi-agent support: Claude Code, Codex, OpenClaw, and generic Agents
+- Configurable providers via `~/.config/skill-manager/config.json`
+- Global and project scope filtering with Tab cycling
+- Real-time search and sort (by name, version, location)
+- Detailed skill view with SKILL.md frontmatter metadata
+- Safe uninstall with confirmation dialog and full removal plan
+- In-TUI config editor — toggle providers on/off or open in `$EDITOR`
+- CLI entry point with `--help` and `--version` flags
+- Neon green logo suite and brand kit
+
+### Infrastructure
+
+- Pre-commit hooks (Prettier, TypeScript type-checking)
+- GitHub Actions CI pipeline (type-check + tests)
+- 63 unit tests covering config, scanner, uninstaller, and frontmatter modules
+- OSS-ready: LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, issue/PR templates
+
+### Install
+
+```bash
+bun install -g agent-skill-manager
+```
+
+**Full Changelog**: https://github.com/luongnv89/skill-manager/commits/v1.0.0

package/SECURITY.md

@@ -0,0 +1,43 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+| ------- | --------- |
+| 1.x     | Yes       |
+
+## Reporting a Vulnerability
+
+We take security vulnerabilities seriously. If you discover a security issue, please report it responsibly.
+
+### How to Report
+
+1. **Do NOT** open a public GitHub issue for security vulnerabilities
+2. Open a [private security advisory](https://github.com/luongnv89/skill-manager/security/advisories/new) on GitHub
+3. Include detailed steps to reproduce the vulnerability
+4. Allow up to 48 hours for an initial response
+
+### What to Include
+
+- Type of vulnerability
+- Full paths of affected source files
+- Location of the affected source code (tag/branch/commit or direct URL)
+- Step-by-step instructions to reproduce
+- Proof-of-concept or exploit code (if possible)
+- Impact of the issue
+
+### What to Expect
+
+- Acknowledgment of your report within 48 hours
+- Regular updates on our progress
+- Credit in the security advisory (if desired)
+- Notification when the issue is fixed
+
+## Security Best Practices
+
+When contributing to this project:
+
+- Never commit secrets, API keys, or credentials
+- Use environment variables for sensitive configuration
+- Follow secure coding practices
+- Report any security concerns immediately

package/bin/skill-manager.ts

@@ -0,0 +1,46 @@
+#!/usr/bin/env bun
+
+import { VERSION, VERSION_STRING } from "../src/utils/version";
+
+const arg = process.argv[2];
+
+if (arg === "--help" || arg === "-h") {
+  console.log(`\x1b[1m\x1b[36mskill-manager\x1b[0m ${VERSION_STRING}
+
+Interactive TUI for managing installed skills for AI coding agents (Claude Code, Codex, OpenClaw, and more).
+
+\x1b[1mUsage:\x1b[0m
+  skill-manager              Launch the interactive TUI dashboard
+  skill-manager --help       Show this help message
+  skill-manager --version    Show version
+
+\x1b[1mRequirements:\x1b[0m
+  Bun >= 1.0.0  (https://bun.sh)
+
+\x1b[1mConfig:\x1b[0m
+  ~/.config/skill-manager/config.json
+
+\x1b[1mTUI Keybindings:\x1b[0m
+  ↑/↓ or j/k   Navigate skill list
+  Enter         View skill details
+  d             Uninstall selected skill
+  /             Search / filter skills
+  Esc           Back / clear filter / close dialog
+  Tab           Cycle scope: Global → Project → Both
+  s             Cycle sort: Name → Version → Location
+  r             Refresh / rescan skills
+  c             Open configuration
+  q             Quit
+  ?             Toggle help overlay`);
+  process.exit(0);
+}
+
+if (arg === "--version" || arg === "-v") {
+  console.log(`skill-manager ${VERSION_STRING}`);
+  process.exit(0);
+}
+
+// Launch the TUI
+await import("../src/index.ts");
+
+export {};