@g3nomaly/skills 1.0.2 → 1.0.3

package/README.md

@@ -0,0 +1,98 @@
+# @g3nomaly/skills
+
+`g3n-skills` installs agent skills into a project, for Claude Code, Codex or both. The package ships no skills of its own. It installs them from sources: git repositories, npm packages and local folders. The g3n skills from [`@g3nomaly/g3n-skills`](https://www.npmjs.com/package/@g3nomaly/g3n-skills) are available by default.
+
+A skill can depend on other skills, from its own source or another one. `add` installs a skill with everything it depends on, and `remove` offers to take the dependents with it.
+
+## Requirements
+
+- [Bun](https://bun.sh). The CLI runs on it, and so do the hooks that skills ship.
+- A git repository to install into. The project root is the root of that repository.
+- `git` on your path, if you register a git source.
+
+## Install skills
+
+Run these from the root of your project:
+
+```sh
+bunx @g3nomaly/skills init                  # picks Claude Code, Codex or both
+bunx @g3nomaly/skills ls                    # lists the skills the sources offer
+bunx @g3nomaly/skills add unslop            # installs one skill
+bunx @g3nomaly/skills add speech            # or a whole group
+```
+
+`init` writes your choice to `.g3n.config.json`. Pass `--targets claude,codex` to skip the prompt. Without `init`, skills go to Claude Code only.
+
+A name given to `add` is a group or a skill. A group is a plugin in the source, such as `speech`, which holds `emphasise` and `unslop`. When a group and a skill share a name, the group wins. Run `add` with no names to pick from a list.
+
+Skills land flat, one folder per skill, in the install directory of each target:
+
+| Target | Skills | Record |
+|---|---|---|
+| `claude` | `.claude/skills/<skill>/` | `.claude/skills.json` |
+| `codex` | `.agents/skills/<skill>/` | `.agents/skills.json` |
+
+`skills.json` records each installed skill: the source it came from, the commit or version it was read at, the skills it depends on, and a SHA-256 hash of every file. It also lists the sources you registered. Commit the skill folders and `skills.json` if your team should get the same skills. The install directories can be changed in `init`.
+
+`-t claude` or `-t codex` limits `add`, `remove`, `update` and the `source` commands to one target.
+
+## Hooks
+
+A skill can ship hooks as TypeScript files in its `hooks/` folder, which Bun runs directly. Nothing is compiled. If a skill has a `package.json`, `add` and `update` run `bun install` inside the skill folder, with `--frozen-lockfile` when it ships a `bun.lock`. The packages go to that skill's own `node_modules`, so your project gets no new dependencies. `remove` deletes that `node_modules` again.
+
+`g3n-skills` does not write `.claude/settings.json`, so a skill's lifecycle hooks (`SessionStart`, `PreToolUse` and the like, listed in a `hooks.json`) are not registered. Those reach a project only when you install the skill as a plugin with `claude plugin`. The g3n `task-manager` skill covers this by telling the agent to run its sync hook itself.
+
+## Keep skills up to date
+
+```sh
+bunx @g3nomaly/skills update                # every installed skill
+bunx @g3nomaly/skills update unslop         # one skill
+bunx @g3nomaly/skills update --dry-run      # shows what would change
+bunx @g3nomaly/skills remove unslop
+bunx @g3nomaly/skills ls --installed
+```
+
+`update` reads each skill again from the source it was installed from. It touches only the skills you name. A skill that gained a dependency since install gets a report of it, and you install the dependency with `add`.
+
+When you have changed an installed file, `add` and `update` ask whether to restore the source version, fork the skill under a new name that updates leave alone, or skip it and ask again next time. Pass `-f` to restore without asking, for example in a script. `remove` asks before it deletes a changed file, and `-f` removes it anyway.
+
+`remove` works from `skills.json` alone, so it never fetches a source.
+
+## Other sources
+
+```sh
+bunx @g3nomaly/skills source add owner/repo                     # a GitHub repository
+bunx @g3nomaly/skills source add https://git.example.com/skills.git --ref v1
+bunx @g3nomaly/skills source add npm:some-skills@^2             # an npm package
+bunx @g3nomaly/skills source add ./my-skills --name mine        # a local folder
+bunx @g3nomaly/skills source ls
+bunx @g3nomaly/skills ls --source mine
+bunx @g3nomaly/skills add greeter@mine                          # a skill from one source
+bunx @g3nomaly/skills source remove mine
+```
+
+`g3n-skills` is built in. It is never written to `skills.json` and cannot be removed.
+
+Git sources take an `https://`, `ssh://`, `git://`, `file://` or `git@` URL, or `owner/repo` for GitHub. Without `--ref` the default branch is used. npm sources are `npm:<package>` or `@scope/package`, with an optional version range. An installed copy in `node_modules` is used when it fits the range, otherwise the CLI downloads the tarball and checks its integrity hash. Set `npm_config_registry` to download from another registry. Local folders start with `.`, `/` or `~`, or with `local:`.
+
+`source add` registers a source only when it offers at least one skill. A source lists its plugins in `.claude-plugin/marketplace.json`, or is one plugin with a root `.claude-plugin/plugin.json`. `.cursor-plugin/` works too. A plugin's skills are the folders its `plugin.json` lists in `skills`, or every folder with a `SKILL.md` under its `skills/` folder. A source with neither manifest is refused.
+
+A skill names the skills it needs in `registryDependencies` in the frontmatter of its `SKILL.md`, as `<skill>` or `<skill>@<source>`. A bare name comes from the skill's own source first, then from the source that skill is already installed from, then from the only source that offers it. If two sources offer it and none of these decides, `add` stops and lists the `<skill>@<source>` names to choose from.
+
+`source remove` refuses while installed skills came from the source. With `-f` they stay installed, and `update` skips them.
+
+## Development
+
+Run `bun install` at the repository root first, then every command from this directory.
+
+```sh
+bun run skills -- ls     # the CLI from source
+bun run typecheck
+bun run build
+```
+
+The reasons behind the design are in `documentation/spec/skills/decisions.md` in the monorepo.
+
+## License
+
+Elastic License 2.0. See `LICENSE`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@g3nomaly/skills",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Installer for skills and their hooks from any registered source: git repositories, npm packages and local folders.",
   "type": "module",
   "bin": {
@@ -24,7 +24,7 @@
     "build:types": "tsc --project tsconfig.build.json"
   },
   "dependencies": {
-    "@g3nomaly/core": "^0.3.2",
+    "@g3nomaly/core": "^0.3.3",
     "@clack/prompts": "^1.7.0",
     "chalk": "^6.0.0",
     "commander": "^15.0.0",