docs: add readme with screenshots
9636cf9 parent: bd9bc8b added
README.md +214 -0 | new file mode 100644 | ||
| @@ -0,0 +1,214 @@ | ||
| 1 | +<p align="center"> | |
| 2 | + <img src="packages/ui/public/skilly-icon.png" alt="skilly" width="96" height="96"> | |
| 3 | +</p> | |
| 4 | + | |
| 5 | +<h1 align="center">skilly</h1> | |
| 6 | + | |
| 7 | +<p align="center"> | |
| 8 | + One place to manage the skills, rules, MCP servers, hooks and subagents of your coding agents,<br> | |
| 9 | + across all your projects. | |
| 10 | +</p> | |
| 11 | + | |
| 12 | +<p align="center"> | |
| 13 | + <img src="media/screenshots/project.png" alt="A project in skilly: presets, items and their sync state" width="900"> | |
| 14 | +</p> | |
| 15 | + | |
| 16 | +--- | |
| 17 | + | |
| 18 | +## Why skilly | |
| 19 | + | |
| 20 | +Coding agents are configured through a growing pile of files: `SKILL.md` folders, rules, `.mcp.json`, `settings.json`, `AGENTS.md`, `config.toml`… Once you use them on more than a couple of projects, three problems show up: | |
| 21 | + | |
| 22 | +- **Lost work.** A skill or a rule written in one project is not available in the next one, so it gets copied by hand, then the copies drift apart. | |
| 23 | +- **Global pollution.** Putting everything in `~/.claude` or `~/.codex` makes every item load in every session of every project. It costs context and triggers skills where they make no sense. | |
| 24 | +- **No overview.** Nothing tells you what exists, where it is used, and which copy is the right one. | |
| 25 | + | |
| 26 | +skilly fixes this with a **catalog** (a git repository holding your items) and a local UI that **writes the right files into each project**, for each agent, and keeps them in sync. | |
| 27 | + | |
| 28 | +## How it works | |
| 29 | + | |
| 30 | +``` | |
| 31 | + ┌────────────── Catalog (git repo) ──────────────┐ | |
| 32 | + │ skills/ rules/ mcp/ hooks/ agents/ │ | |
| 33 | + │ presets/ nuxt-saas = nuxt + tailwind + … │ | |
| 34 | + └────────────────────────┬───────────────────────┘ | |
| 35 | + │ you pick presets and items per project | |
| 36 | + ┌─────────────────────┼─────────────────────┐ | |
| 37 | + ▼ ▼ ▼ | |
| 38 | + acme-shop/ billing-api/ blog/ | |
| 39 | + .claude/skills/… .agents/skills/… .claude/skills/… | |
| 40 | + .agents/skills/… AGENTS.md (block) .claude/rules/… | |
| 41 | + .mcp.json .codex/config.toml skilly.json | |
| 42 | + skilly.json skilly.json | |
| 43 | +``` | |
| 44 | + | |
| 45 | +- **The catalog is the source of truth.** It is a plain git repository, hosted wherever you like (or nowhere). Sync it across your machines or share it with your team. | |
| 46 | +- **Enabling an item writes real files into the project**, where each agent expects them. The project then works without skilly, for you and for anyone who clones it. You commit those files with the project. | |
| 47 | +- **Nothing is written until you apply.** Every change goes through a review, and a file edited by hand is never overwritten without asking. | |
| 48 | +- **Global stays minimal.** Keep in `~` only what you really use everywhere, and move the rest to the projects that need it. | |
| 49 | + | |
| 50 | +### Vocabulary | |
| 51 | + | |
| 52 | +| Term | Meaning | | |
| 53 | +|---|---| | |
| 54 | +| **Item** | A skill, rule, MCP server, hook or subagent. | | |
| 55 | +| **Catalog** | Your library of items and presets, stored in a git repository. | | |
| 56 | +| **Preset** | A named bundle of items, for example *nuxt-saas* = Nuxt and Tailwind skills, TypeScript rules and the Nuxt docs MCP server. A preset can include other presets. | | |
| 57 | +| **Project** | A code folder you added to skilly. | | |
| 58 | +| **Global** | Your user-level agent configuration (`~/.claude`, `~/.agents`, `~/.codex`). It loads in every project. | | |
| 59 | +| **Automatic / on demand** | Skill mode. *Automatic*: the agent sees the skill and uses it when it thinks it is relevant. *On demand*: the skill is installed but hidden from the agent until you call it yourself (`/name` in Claude Code, `$name` in Codex). Ideal for large families of niche skills you want at hand without paying for them in context. | | |
| 60 | + | |
| 61 | +## A tour | |
| 62 | + | |
| 63 | +### Projects: choose what each project uses | |
| 64 | + | |
| 65 | +Pick presets, add or exclude single items, switch skills between automatic and on demand, and hide Global items you do not want in this project. Each item shows where it comes from (preset, catalog, local) and its state for every agent. | |
| 66 | + | |
| 67 | +### Review before anything is written | |
| 68 | + | |
| 69 | +skilly computes a plan: files to add, update or remove, for each agent. You can undo any line before applying. When a file already exists or was edited by hand, you choose: **keep the project version**, **take the catalog version**, or **push the change back to the catalog**. You can compare both versions first. | |
| 70 | + | |
| 71 | +<p align="center"> | |
| 72 | + <img src="media/screenshots/review.png" alt="Review changes before applying them, with conflict resolution" width="900"> | |
| 73 | +</p> | |
| 74 | + | |
| 75 | +### Clean up Global | |
| 76 | + | |
| 77 | +skilly lists everything loaded from your home folder and spots the items that are only used in some projects. **Move to projects** copies them to the catalog, enables them where they are needed, then removes them from Global. Nothing is removed from your home folder without an explicit action. | |
| 78 | + | |
| 79 | +<p align="center"> | |
| 80 | + <img src="media/screenshots/global.png" alt="Global items loaded in every project, with tidy-up suggestions" width="900"> | |
| 81 | +</p> | |
| 82 | + | |
| 83 | +### Catalog: your library of items | |
| 84 | + | |
| 85 | +Import what already exists on your machine (from Global or from any project), or write new items in the built-in editor: Markdown with preview for skills, rules and subagents, a form for MCP servers and hooks. Tag and search items, and see which projects use each one. | |
| 86 | + | |
| 87 | +<p align="center"> | |
| 88 | + <img src="media/screenshots/catalog.png" alt="The catalog with a skill opened" width="900"> | |
| 89 | +</p> | |
| 90 | + | |
| 91 | +### Presets: bundles you enable in one click | |
| 92 | + | |
| 93 | +<p align="center"> | |
| 94 | + <img src="media/screenshots/presets.png" alt="Presets with their items and usage" width="900"> | |
| 95 | +</p> | |
| 96 | + | |
| 97 | +### Marketplaces: import skills from others | |
| 98 | + | |
| 99 | +Browse skill sources and import what you want into your catalog. Three sources are built in ([Anthropic Skills](https://github.com/anthropics/skills), [Claude Code official plugins](https://github.com/anthropics/claude-plugins-official), [Vercel Agent Skills](https://github.com/vercel-labs/agent-skills)), and you can add any git repository or Claude plugin marketplace. | |
| 100 | + | |
| 101 | +<p align="center"> | |
| 102 | + <img src="media/screenshots/marketplaces.png" alt="Browsing a marketplace" width="900"> | |
| 103 | +</p> | |
| 104 | + | |
| 105 | +### Sync: the catalog is a git repository | |
| 106 | + | |
| 107 | +Commit, pull and push from the UI, against any remote: GitHub, GitLab, Codeberg, rickub, a self-hosted server… Conflicts are resolved file by file. An optional automatic mode commits and syncs after each change. On a new machine, clone your catalog during setup, add your projects, and you are back. | |
| 108 | + | |
| 109 | +## Supported agents and items | |
| 110 | + | |
| 111 | +| | Claude Code | Codex | | |
| 112 | +|---|---|---| | |
| 113 | +| Skills | `.claude/skills/<name>/` | `.agents/skills/<name>/` | | |
| 114 | +| On-demand skills | `skillOverrides` in `.claude/settings.json` | `agents/openai.yaml` in the skill folder | | |
| 115 | +| Rules | `.claude/rules/<name>.md` (with optional `paths`) | Managed block in `AGENTS.md` | | |
| 116 | +| MCP servers | `.mcp.json` | `.codex/config.toml` | | |
| 117 | +| Hooks | `hooks` in `.claude/settings.json` | `.codex/hooks.json` | | |
| 118 | +| Subagents | `.claude/agents/<name>.md` | `.codex/agents/<name>.toml` | | |
| 119 | +| Hide a Global skill or MCP server | Yes | Not supported by Codex yet | | |
| 120 | + | |
| 121 | +skilly also writes two files at the root of each project, meant to be committed: | |
| 122 | + | |
| 123 | +- **`skilly.json`**: what the project uses (target agents, presets, added and excluded items, on-demand skills, hidden Global items). | |
| 124 | +- **`skilly.lock`**: what skilly installed, with content hashes, so it knows which files it owns and can detect manual edits. | |
| 125 | + | |
| 126 | +Shared files (`.mcp.json`, `.claude/settings.json`, `.codex/config.toml`, `AGENTS.md`) are edited surgically: skilly only touches the keys or the block it owns and leaves the rest as is. | |
| 127 | + | |
| 128 | +skilly also warns you about agent-specific pitfalls: a Codex project that is not trusted (Codex then ignores its `.codex/` folder), an `AGENTS.md` close to the 32 KiB Codex limit, or rules that Claude Code would load twice. | |
| 129 | + | |
| 130 | +`CLAUDE.md` and `AGENTS.md` are shown read-only in each project, with their size. They are specific to each project and never go into the catalog. | |
| 131 | + | |
| 132 | +## Install and run | |
| 133 | + | |
| 134 | +> skilly is in early development and not published on npm yet. Until the first release, run it from source (see below). | |
| 135 | + | |
| 136 | +Requirements: **Node.js 22+**, **git**, and preferably **Microsoft Edge or Google Chrome** for the app window. | |
| 137 | + | |
| 138 | +```sh | |
| 139 | +npx @skilly/cli | |
| 140 | +``` | |
| 141 | + | |
| 142 | +skilly starts a local server and opens the UI in an app window (Edge or Chrome in app mode, your default browser otherwise). Closing the window stops skilly. Running the command again while skilly is open brings the existing window back. | |
| 143 | + | |
| 144 | +| Option | Effect | | |
| 145 | +|---|---| | |
| 146 | +| `--no-open` | Do not open a window, only print the URL. | | |
| 147 | +| `--port <n>` | Use this port instead of the default one (47821, or a free port if taken). | | |
| 148 | + | |
| 149 | +The first launch walks you through the setup: create a new catalog or clone an existing one from git, check the detected agents, then add your projects (skilly can scan your usual code folders for you). | |
| 150 | + | |
| 151 | +### From source | |
| 152 | + | |
| 153 | +```sh | |
| 154 | +git clone <repository-url> skilly | |
| 155 | +cd skilly | |
| 156 | +pnpm install | |
| 157 | +pnpm build # builds the UI | |
| 158 | +pnpm start # starts skilly and opens the window | |
| 159 | +``` | |
| 160 | + | |
| 161 | +## Where your data lives | |
| 162 | + | |
| 163 | +| What | Where | | |
| 164 | +|---|---| | |
| 165 | +| Catalog | `~/.skilly/catalog` by default (a git repository, the location can be changed in Settings) | | |
| 166 | +| Machine settings (projects list, preferences, Global configuration) | `~/.skilly/` | | |
| 167 | +| Project configuration | `skilly.json` and `skilly.lock` in each project | | |
| 168 | + | |
| 169 | +Set `SKILLY_CONFIG_DIR` to use another folder than `~/.skilly`, and `CODEX_HOME` if your Codex home is not `~/.codex`. | |
| 170 | + | |
| 171 | +## Security and privacy | |
| 172 | + | |
| 173 | +- **Local only.** The server listens on `127.0.0.1`, rejects other host names, and requires a random token generated at each launch, so other websites open in your browser cannot call it. | |
| 174 | +- **No secrets in the catalog.** MCP configurations store the *name* of environment variables, never their values. Credentials found in MCP arguments, URLs or environment when importing are redacted. | |
| 175 | +- **Limited writes.** skilly writes only in the projects you added, in the catalog, and in your home folder when you explicitly apply a change to Global. | |
| 176 | +- **No telemetry.** skilly only goes online to fetch the marketplace sources you browse and to sync your catalog with the git remote you configure. | |
| 177 | +- skilly never executes the scripts contained in skills. | |
| 178 | + | |
| 179 | +## FAQ | |
| 180 | + | |
| 181 | +**Do my teammates need skilly?** | |
| 182 | +No. The generated files are regular agent files committed in the project. skilly only makes them easier to manage, and it makes catalog sharing easier for those who use it. | |
| 183 | + | |
| 184 | +**What if I edit a generated file by hand?** | |
| 185 | +skilly detects it (thanks to `skilly.lock`) and asks what to do on the next apply: keep your version, take the catalog version, or push your change back to the catalog. | |
| 186 | + | |
| 187 | +**Why are skills copied twice instead of symlinked?** | |
| 188 | +Claude Code reads `.claude/skills` and Codex reads `.agents/skills`. Symlinks are fragile on Windows and do not survive a clone, so skilly writes plain copies and keeps them in sync. | |
| 189 | + | |
| 190 | +**Does it work with other agents (Cursor, Copilot, Gemini CLI…)?** | |
| 191 | +Not yet. Claude Code and Codex are supported today; more agents are planned. | |
| 192 | + | |
| 193 | +## Development | |
| 194 | + | |
| 195 | +The repository is a TypeScript monorepo managed with pnpm: | |
| 196 | + | |
| 197 | +| Package | Role | | |
| 198 | +|---|---| | |
| 199 | +| `packages/core` | Model, inventory scanners, catalog, resolution, rendering per agent, sync plan and apply. No UI dependency. | | |
| 200 | +| `packages/server` | Local HTTP API over `core`. | | |
| 201 | +| `packages/ui` | Nuxt single-page app served by the server. | | |
| 202 | +| `packages/cli` | The `skilly` command: starts the server and opens the window. | | |
| 203 | + | |
| 204 | +```sh | |
| 205 | +pnpm dev # API on :4300 and the UI with hot reload on :3000 | |
| 206 | +pnpm test # Vitest | |
| 207 | +pnpm typecheck | |
| 208 | +``` | |
| 209 | + | |
| 210 | +Commits follow [Conventional Commits](https://www.conventionalcommits.org/). | |
| 211 | + | |
| 212 | +## License | |
| 213 | + | |
| 214 | +[MIT](LICENSE) | |
| new file mode 100644 | |||
| @@ -0,0 +1,214 @@ | |||
| 1 | +<p align="center"> | ||
| 2 | + <img src="packages/ui/public/skilly-icon.png" alt="skilly" width="96" height="96"> | ||
| 3 | +</p> | ||
| 4 | + | ||
| 5 | +<h1 align="center">skilly</h1> | ||
| 6 | + | ||
| 7 | +<p align="center"> | ||
| 8 | + One place to manage the skills, rules, MCP servers, hooks and subagents of your coding agents,<br> | ||
| 9 | + across all your projects. | ||
| 10 | +</p> | ||
| 11 | + | ||
| 12 | +<p align="center"> | ||
| 13 | + <img src="media/screenshots/project.png" alt="A project in skilly: presets, items and their sync state" width="900"> | ||
| 14 | +</p> | ||
| 15 | + | ||
| 16 | +--- | ||
| 17 | + | ||
| 18 | +## Why skilly | ||
| 19 | + | ||
| 20 | +Coding agents are configured through a growing pile of files: `SKILL.md` folders, rules, `.mcp.json`, `settings.json`, `AGENTS.md`, `config.toml`… Once you use them on more than a couple of projects, three problems show up: | ||
| 21 | + | ||
| 22 | +- **Lost work.** A skill or a rule written in one project is not available in the next one, so it gets copied by hand, then the copies drift apart. | ||
| 23 | +- **Global pollution.** Putting everything in `~/.claude` or `~/.codex` makes every item load in every session of every project. It costs context and triggers skills where they make no sense. | ||
| 24 | +- **No overview.** Nothing tells you what exists, where it is used, and which copy is the right one. | ||
| 25 | + | ||
| 26 | +skilly fixes this with a **catalog** (a git repository holding your items) and a local UI that **writes the right files into each project**, for each agent, and keeps them in sync. | ||
| 27 | + | ||
| 28 | +## How it works | ||
| 29 | + | ||
| 30 | +``` | ||
| 31 | + ┌────────────── Catalog (git repo) ──────────────┐ | ||
| 32 | + │ skills/ rules/ mcp/ hooks/ agents/ │ | ||
| 33 | + │ presets/ nuxt-saas = nuxt + tailwind + … │ | ||
| 34 | + └────────────────────────┬───────────────────────┘ | ||
| 35 | + │ you pick presets and items per project | ||
| 36 | + ┌─────────────────────┼─────────────────────┐ | ||
| 37 | + ▼ ▼ ▼ | ||
| 38 | + acme-shop/ billing-api/ blog/ | ||
| 39 | + .claude/skills/… .agents/skills/… .claude/skills/… | ||
| 40 | + .agents/skills/… AGENTS.md (block) .claude/rules/… | ||
| 41 | + .mcp.json .codex/config.toml skilly.json | ||
| 42 | + skilly.json skilly.json | ||
| 43 | +``` | ||
| 44 | + | ||
| 45 | +- **The catalog is the source of truth.** It is a plain git repository, hosted wherever you like (or nowhere). Sync it across your machines or share it with your team. | ||
| 46 | +- **Enabling an item writes real files into the project**, where each agent expects them. The project then works without skilly, for you and for anyone who clones it. You commit those files with the project. | ||
| 47 | +- **Nothing is written until you apply.** Every change goes through a review, and a file edited by hand is never overwritten without asking. | ||
| 48 | +- **Global stays minimal.** Keep in `~` only what you really use everywhere, and move the rest to the projects that need it. | ||
| 49 | + | ||
| 50 | +### Vocabulary | ||
| 51 | + | ||
| 52 | +| Term | Meaning | | ||
| 53 | +|---|---| | ||
| 54 | +| **Item** | A skill, rule, MCP server, hook or subagent. | | ||
| 55 | +| **Catalog** | Your library of items and presets, stored in a git repository. | | ||
| 56 | +| **Preset** | A named bundle of items, for example *nuxt-saas* = Nuxt and Tailwind skills, TypeScript rules and the Nuxt docs MCP server. A preset can include other presets. | | ||
| 57 | +| **Project** | A code folder you added to skilly. | | ||
| 58 | +| **Global** | Your user-level agent configuration (`~/.claude`, `~/.agents`, `~/.codex`). It loads in every project. | | ||
| 59 | +| **Automatic / on demand** | Skill mode. *Automatic*: the agent sees the skill and uses it when it thinks it is relevant. *On demand*: the skill is installed but hidden from the agent until you call it yourself (`/name` in Claude Code, `$name` in Codex). Ideal for large families of niche skills you want at hand without paying for them in context. | | ||
| 60 | + | ||
| 61 | +## A tour | ||
| 62 | + | ||
| 63 | +### Projects: choose what each project uses | ||
| 64 | + | ||
| 65 | +Pick presets, add or exclude single items, switch skills between automatic and on demand, and hide Global items you do not want in this project. Each item shows where it comes from (preset, catalog, local) and its state for every agent. | ||
| 66 | + | ||
| 67 | +### Review before anything is written | ||
| 68 | + | ||
| 69 | +skilly computes a plan: files to add, update or remove, for each agent. You can undo any line before applying. When a file already exists or was edited by hand, you choose: **keep the project version**, **take the catalog version**, or **push the change back to the catalog**. You can compare both versions first. | ||
| 70 | + | ||
| 71 | +<p align="center"> | ||
| 72 | + <img src="media/screenshots/review.png" alt="Review changes before applying them, with conflict resolution" width="900"> | ||
| 73 | +</p> | ||
| 74 | + | ||
| 75 | +### Clean up Global | ||
| 76 | + | ||
| 77 | +skilly lists everything loaded from your home folder and spots the items that are only used in some projects. **Move to projects** copies them to the catalog, enables them where they are needed, then removes them from Global. Nothing is removed from your home folder without an explicit action. | ||
| 78 | + | ||
| 79 | +<p align="center"> | ||
| 80 | + <img src="media/screenshots/global.png" alt="Global items loaded in every project, with tidy-up suggestions" width="900"> | ||
| 81 | +</p> | ||
| 82 | + | ||
| 83 | +### Catalog: your library of items | ||
| 84 | + | ||
| 85 | +Import what already exists on your machine (from Global or from any project), or write new items in the built-in editor: Markdown with preview for skills, rules and subagents, a form for MCP servers and hooks. Tag and search items, and see which projects use each one. | ||
| 86 | + | ||
| 87 | +<p align="center"> | ||
| 88 | + <img src="media/screenshots/catalog.png" alt="The catalog with a skill opened" width="900"> | ||
| 89 | +</p> | ||
| 90 | + | ||
| 91 | +### Presets: bundles you enable in one click | ||
| 92 | + | ||
| 93 | +<p align="center"> | ||
| 94 | + <img src="media/screenshots/presets.png" alt="Presets with their items and usage" width="900"> | ||
| 95 | +</p> | ||
| 96 | + | ||
| 97 | +### Marketplaces: import skills from others | ||
| 98 | + | ||
| 99 | +Browse skill sources and import what you want into your catalog. Three sources are built in ([Anthropic Skills](https://github.com/anthropics/skills), [Claude Code official plugins](https://github.com/anthropics/claude-plugins-official), [Vercel Agent Skills](https://github.com/vercel-labs/agent-skills)), and you can add any git repository or Claude plugin marketplace. | ||
| 100 | + | ||
| 101 | +<p align="center"> | ||
| 102 | + <img src="media/screenshots/marketplaces.png" alt="Browsing a marketplace" width="900"> | ||
| 103 | +</p> | ||
| 104 | + | ||
| 105 | +### Sync: the catalog is a git repository | ||
| 106 | + | ||
| 107 | +Commit, pull and push from the UI, against any remote: GitHub, GitLab, Codeberg, rickub, a self-hosted server… Conflicts are resolved file by file. An optional automatic mode commits and syncs after each change. On a new machine, clone your catalog during setup, add your projects, and you are back. | ||
| 108 | + | ||
| 109 | +## Supported agents and items | ||
| 110 | + | ||
| 111 | +| | Claude Code | Codex | | ||
| 112 | +|---|---|---| | ||
| 113 | +| Skills | `.claude/skills/<name>/` | `.agents/skills/<name>/` | | ||
| 114 | +| On-demand skills | `skillOverrides` in `.claude/settings.json` | `agents/openai.yaml` in the skill folder | | ||
| 115 | +| Rules | `.claude/rules/<name>.md` (with optional `paths`) | Managed block in `AGENTS.md` | | ||
| 116 | +| MCP servers | `.mcp.json` | `.codex/config.toml` | | ||
| 117 | +| Hooks | `hooks` in `.claude/settings.json` | `.codex/hooks.json` | | ||
| 118 | +| Subagents | `.claude/agents/<name>.md` | `.codex/agents/<name>.toml` | | ||
| 119 | +| Hide a Global skill or MCP server | Yes | Not supported by Codex yet | | ||
| 120 | + | ||
| 121 | +skilly also writes two files at the root of each project, meant to be committed: | ||
| 122 | + | ||
| 123 | +- **`skilly.json`**: what the project uses (target agents, presets, added and excluded items, on-demand skills, hidden Global items). | ||
| 124 | +- **`skilly.lock`**: what skilly installed, with content hashes, so it knows which files it owns and can detect manual edits. | ||
| 125 | + | ||
| 126 | +Shared files (`.mcp.json`, `.claude/settings.json`, `.codex/config.toml`, `AGENTS.md`) are edited surgically: skilly only touches the keys or the block it owns and leaves the rest as is. | ||
| 127 | + | ||
| 128 | +skilly also warns you about agent-specific pitfalls: a Codex project that is not trusted (Codex then ignores its `.codex/` folder), an `AGENTS.md` close to the 32 KiB Codex limit, or rules that Claude Code would load twice. | ||
| 129 | + | ||
| 130 | +`CLAUDE.md` and `AGENTS.md` are shown read-only in each project, with their size. They are specific to each project and never go into the catalog. | ||
| 131 | + | ||
| 132 | +## Install and run | ||
| 133 | + | ||
| 134 | +> skilly is in early development and not published on npm yet. Until the first release, run it from source (see below). | ||
| 135 | + | ||
| 136 | +Requirements: **Node.js 22+**, **git**, and preferably **Microsoft Edge or Google Chrome** for the app window. | ||
| 137 | + | ||
| 138 | +```sh | ||
| 139 | +npx @skilly/cli | ||
| 140 | +``` | ||
| 141 | + | ||
| 142 | +skilly starts a local server and opens the UI in an app window (Edge or Chrome in app mode, your default browser otherwise). Closing the window stops skilly. Running the command again while skilly is open brings the existing window back. | ||
| 143 | + | ||
| 144 | +| Option | Effect | | ||
| 145 | +|---|---| | ||
| 146 | +| `--no-open` | Do not open a window, only print the URL. | | ||
| 147 | +| `--port <n>` | Use this port instead of the default one (47821, or a free port if taken). | | ||
| 148 | + | ||
| 149 | +The first launch walks you through the setup: create a new catalog or clone an existing one from git, check the detected agents, then add your projects (skilly can scan your usual code folders for you). | ||
| 150 | + | ||
| 151 | +### From source | ||
| 152 | + | ||
| 153 | +```sh | ||
| 154 | +git clone <repository-url> skilly | ||
| 155 | +cd skilly | ||
| 156 | +pnpm install | ||
| 157 | +pnpm build # builds the UI | ||
| 158 | +pnpm start # starts skilly and opens the window | ||
| 159 | +``` | ||
| 160 | + | ||
| 161 | +## Where your data lives | ||
| 162 | + | ||
| 163 | +| What | Where | | ||
| 164 | +|---|---| | ||
| 165 | +| Catalog | `~/.skilly/catalog` by default (a git repository, the location can be changed in Settings) | | ||
| 166 | +| Machine settings (projects list, preferences, Global configuration) | `~/.skilly/` | | ||
| 167 | +| Project configuration | `skilly.json` and `skilly.lock` in each project | | ||
| 168 | + | ||
| 169 | +Set `SKILLY_CONFIG_DIR` to use another folder than `~/.skilly`, and `CODEX_HOME` if your Codex home is not `~/.codex`. | ||
| 170 | + | ||
| 171 | +## Security and privacy | ||
| 172 | + | ||
| 173 | +- **Local only.** The server listens on `127.0.0.1`, rejects other host names, and requires a random token generated at each launch, so other websites open in your browser cannot call it. | ||
| 174 | +- **No secrets in the catalog.** MCP configurations store the *name* of environment variables, never their values. Credentials found in MCP arguments, URLs or environment when importing are redacted. | ||
| 175 | +- **Limited writes.** skilly writes only in the projects you added, in the catalog, and in your home folder when you explicitly apply a change to Global. | ||
| 176 | +- **No telemetry.** skilly only goes online to fetch the marketplace sources you browse and to sync your catalog with the git remote you configure. | ||
| 177 | +- skilly never executes the scripts contained in skills. | ||
| 178 | + | ||
| 179 | +## FAQ | ||
| 180 | + | ||
| 181 | +**Do my teammates need skilly?** | ||
| 182 | +No. The generated files are regular agent files committed in the project. skilly only makes them easier to manage, and it makes catalog sharing easier for those who use it. | ||
| 183 | + | ||
| 184 | +**What if I edit a generated file by hand?** | ||
| 185 | +skilly detects it (thanks to `skilly.lock`) and asks what to do on the next apply: keep your version, take the catalog version, or push your change back to the catalog. | ||
| 186 | + | ||
| 187 | +**Why are skills copied twice instead of symlinked?** | ||
| 188 | +Claude Code reads `.claude/skills` and Codex reads `.agents/skills`. Symlinks are fragile on Windows and do not survive a clone, so skilly writes plain copies and keeps them in sync. | ||
| 189 | + | ||
| 190 | +**Does it work with other agents (Cursor, Copilot, Gemini CLI…)?** | ||
| 191 | +Not yet. Claude Code and Codex are supported today; more agents are planned. | ||
| 192 | + | ||
| 193 | +## Development | ||
| 194 | + | ||
| 195 | +The repository is a TypeScript monorepo managed with pnpm: | ||
| 196 | + | ||
| 197 | +| Package | Role | | ||
| 198 | +|---|---| | ||
| 199 | +| `packages/core` | Model, inventory scanners, catalog, resolution, rendering per agent, sync plan and apply. No UI dependency. | | ||
| 200 | +| `packages/server` | Local HTTP API over `core`. | | ||
| 201 | +| `packages/ui` | Nuxt single-page app served by the server. | | ||
| 202 | +| `packages/cli` | The `skilly` command: starts the server and opens the window. | | ||
| 203 | + | ||
| 204 | +```sh | ||
| 205 | +pnpm dev # API on :4300 and the UI with hot reload on :3000 | ||
| 206 | +pnpm test # Vitest | ||
| 207 | +pnpm typecheck | ||
| 208 | +``` | ||
| 209 | + | ||
| 210 | +Commits follow [Conventional Commits](https://www.conventionalcommits.org/). | ||
| 211 | + | ||
| 212 | +## License | ||
| 213 | + | ||
| 214 | +[MIT](LICENSE) | ||
added
media/screenshots/catalog.png +0 -0 | new file mode 100644 | ||
| Binary files /dev/null and b/media/screenshots/catalog.png differ | ||
| new file mode 100644 | |||
| Binary files /dev/null and b/media/screenshots/catalog.png differ | Binary files /dev/null and b/media/screenshots/catalog.png differ | ||
added
media/screenshots/global.png +0 -0 | new file mode 100644 | ||
| Binary files /dev/null and b/media/screenshots/global.png differ | ||
| new file mode 100644 | |||
| Binary files /dev/null and b/media/screenshots/global.png differ | Binary files /dev/null and b/media/screenshots/global.png differ | ||
added
media/screenshots/marketplaces.png +0 -0 | new file mode 100644 | ||
| Binary files /dev/null and b/media/screenshots/marketplaces.png differ | ||
| new file mode 100644 | |||
| Binary files /dev/null and b/media/screenshots/marketplaces.png differ | Binary files /dev/null and b/media/screenshots/marketplaces.png differ | ||
added
media/screenshots/presets.png +0 -0 | new file mode 100644 | ||
| Binary files /dev/null and b/media/screenshots/presets.png differ | ||
| new file mode 100644 | |||
| Binary files /dev/null and b/media/screenshots/presets.png differ | Binary files /dev/null and b/media/screenshots/presets.png differ | ||
added
media/screenshots/project.png +0 -0 | new file mode 100644 | ||
| Binary files /dev/null and b/media/screenshots/project.png differ | ||
| new file mode 100644 | |||
| Binary files /dev/null and b/media/screenshots/project.png differ | Binary files /dev/null and b/media/screenshots/project.png differ | ||
added
media/screenshots/review.png +0 -0 | new file mode 100644 | ||
| Binary files /dev/null and b/media/screenshots/review.png differ | ||
| new file mode 100644 | |||
| Binary files /dev/null and b/media/screenshots/review.png differ | Binary files /dev/null and b/media/screenshots/review.png differ | ||