apps/skills/cli contains the source for newth-skills, a separate command-line manager. For installation of committed instruction files, use the shell installer.
Distribution status#
The CLI manifest declares package name newth-skills, version 1.0.0, and executable dist/index.js. These declarations do not establish that an npm release is available. During this documentation review on 2026-09-17, the public registry returned HTTP 404 for both the package metadata and its latest endpoint. Do not rely on npx newth-skills or an npm global install as a verified distribution route.
The checked-in CLI download base is https://raw.githubusercontent.com/n3wth/n3wth/main/apps/skills/skills. The shell installer also targets the current n3wth/n3wth repository. If an older installation points at the former standalone n3wth/skills repository, it does not match this source. Inspect its bundled URLs before trusting downloads; a failed fetch can be hidden by generated fallback content.
The CLI is nested below apps/skills and is not a separate member of the root's apps/* workspace list. It has its own manifest and lockfile. Its manifest declares Node >=18.0.0, but that declaration alone does not verify compatibility of its dependencies or a successful build. The repository's current development requirement is Node 24 and npm 11.19.1.
Sources: CLI manifest, download implementation, and public registry metadata endpoint.
Commands implemented in source#
The syntax below describes the checked-in implementation. It assumes you already have a working executable built from the source; it is not an npm installation promise.
| Command | Options | Behavior |
|---|---|---|
newth-skills list | -c, --category <category>; -i, --installed; -f, --featured | Lists the bundled catalog with combined filters |
newth-skills search <query> | None | Case-insensitive substring search across name, description, tags, and category |
newth-skills info <skill-id> | None | Displays catalog details and tracking status; attempts a fetch when skillFile exists |
newth-skills install <skill-id> | -p, --platform <platform>; -f, --force | Writes a flat file and records the catalog version; only gemini is accepted |
newth-skills uninstall <skill-id> | None | Removes a tracked flat file and its tracking record |
newth-skills update | None | Rewrites tracked skills whose bundled catalog version differs from the recorded version |
newth-skills --help | -h | Shows command help |
newth-skills --version | -V | Prints the program's declared version |
For an existing executable:
Category filtering uses exact IDs. The help text lists fewer categories than the type supports; available results come from the CLI's bundled catalog. Search includes categories, unlike the website's name/description/tag search.
Files and tracking#
| Path | Purpose |
|---|---|
~/.newth-skills/config.json | installedSkills records containing id, version, installedAt, and platform; also a lastUpdated field initialized to null |
~/.gemini/skills/<id>.md | Instruction or fallback content written by the CLI |
Config reads create the config directory and default file if missing. Even a listing can therefore write local state. Malformed config JSON is treated as an empty configuration.
Tracking is not a scan of ~/.gemini/skills. Files installed through the shell script, copied manually, or downloaded by curl are not automatically registered. Conversely, a tracking entry does not prove the file still exists.
--force bypasses the existing tracking-record check. It does not protect untracked files: an install can overwrite an existing <id>.md even without --force. The CLI always writes a flat file, including when its URL ends in /SKILL.md.
What success messages do not prove#
When skillFile is absent or the fetch fails, install and update generate Markdown from catalog descriptions, features, and use cases. This fallback is not the authored instruction file and has no YAML frontmatter. A successful network fetch is not required for an install success message.
The install helper catches file-write errors internally, but the caller still records the installation and prints success. Uninstall similarly catches file-removal errors before removing the tracking record. Verify the actual file after either operation rather than relying solely on output or exit status.
update compares version strings against the bundled catalog. It does not fetch a current catalog, compare semantic-version ordering, or update the CLI itself. A different version string triggers rewriting even if it represents an older version. Unchanged version strings mean changed remote content is not fetched.
Troubleshooting#
| Symptom | Explanation and next step |
|---|---|
| npm returns 404 | A public package was not available at review time; use the shell installer |
| CLI cannot find a website skill | Its catalog is separate and may have no matching record |
| File contains only descriptive bullets | Download failed or no URL was configured; obtain the authored file through the shell installer |
list --installed omits existing files | CLI tracking does not include shell or manual installations |
| Install says success but file is absent | Check filesystem permissions and inspect the target directly; the source can swallow write errors |
| Update says all skills are current | It only compared versions in its bundled catalog |
| Uninstall leaves a skill folder behind | It targets <id>.md, not <id>/SKILL.md; remove only the folder you intentionally installed |