personal-skills

The CLI for the open agent skills ecosystem.

Installs skills from the private LongTranPTN/PersonalSkills catalog. Supports Cursor, Claude Code, Codex, Antigravity, and GitHub Copilot.

Because the catalog is private, you can authenticate in either of these ways:

1. Use your existing Git credentials.
2. Use a GitHub access token. You can quickly create a 30-day token here. Select Only select repositories, choose PersonalSkills, and generate the token.

Using the CLI

Start the interactive installer:

npx personal-skills

Commands

| Command | Meaning | | --- | --- | | npx personal-skills | Choose skills, a target project, and an agent interactively. | | npx personal-skills list | Display the available skill tree. Alias: ls. | | npx personal-skills find [query] | Search for skills interactively or by keyword. | | npx personal-skills add <skill...> | Install one or more skills by name. | | npx personal-skills add --category <path> | Install every skill below a catalog folder. | | npx personal-skills add --all | Install the complete catalog. | | npx personal-skills remove [skills...] | Remove installed skills from an agent. Alias: rm. | | npx personal-skills update [skills...] | Update installed skills from the catalog. Alias: upgrade. | | npx personal-skills --help | Display CLI help. | | npx personal-skills --version | Display the CLI version. |

Add options

| Option | Meaning | | --- | --- | | -a, --agent <agent> | Select the target agent. | | -p, --path <project> | Select the target project. Defaults to the current directory. | | -c, --category <path> | Select a category. Repeat the option to combine categories. | | --all | Select every available skill. | | --auth <git\|token> | Use existing Git credentials or a GitHub token. | | --ref <branch-or-tag> | Read a specific repository branch or tag. | | --skills-path <path> | Read another catalog folder. Defaults to skills. |

Examples

# List available skills
npx personal-skills list

# Search interactively or by keyword
npx personal-skills find
npx personal-skills find react

# Install one skill
npx personal-skills add react-component-design --agent codex

# Install multiple skills
npx personal-skills add react-component-design react-testing --agent cursor

# Install every React skill
npx personal-skills add --category common/frontend/reactjs --agent github-copilot

# Install multiple categories
npx personal-skills add \
  --category common/frontend/reactjs \
  --category project/ptn \
  --agent claude-code

# Install everything into another project
npx personal-skills add --all --agent codex --path ../my-project

# Remove installed skills
npx personal-skills remove react-testing --agent codex

# Update selected skills, or choose interactively when names are omitted
npx personal-skills update react-component-design --agent codex
npx personal-skills update --agent codex

The catalog supports any number of category levels. Only directories containing SKILL.md are installable. Existing skills in the target project are skipped and never overwritten.

Interactive menus show ← Back as the first option. Use it to return to the previous step; inside category navigation, it returns to the parent folder. Displayed trees stop at the skill directory and do not include a separate SKILL.md line.

remove and update operate only on installed skills inside the selected agent's project path. They do not change the source catalog in this repository.

Supported agents

| Agent | --agent value | Project installation path | | --- | --- | --- | | Cursor | cursor | .agents/skills/<skill>/ | | Claude Code | claude-code | .claude/skills/<skill>/ | | Codex | codex | .agents/skills/<skill>/ | | Antigravity | antigravity | .agents/skills/<skill>/ | | GitHub Copilot | github-copilot | .github/skills/<skill>/ |

Private repository authentication

Interactive commands offer existing Git credentials or a masked GitHub access token prompt.

For non-interactive token authentication in PowerShell:

$env:PERSONAL_SKILLS_TOKEN = "github_pat_xxx"
npx personal-skills list --auth token
Remove-Item Env:PERSONAL_SKILLS_TOKEN

The token is sent only in GitHub API request headers. It is not logged or stored in the project.

Maintaining the skill system

This section is for maintainers of the PersonalSkills repository. These operations change the source catalog or the CLI itself. They do not modify projects where skills were previously installed.

| Changed files | Push to GitHub | Publish the npm CLI | | --- | --- | --- | | skills/** only | Yes | No | | CLI code such as src/**, bin/**, or package configuration | Yes | Yes |

When only adding, updating, moving, or deleting skills, commit and push the catalog to GitHub. Do not run npm publish. The CLI loads the current skill catalog directly from GitHub.

Catalog structure

skills/
├── common/                         # Reusable skills
│   ├── frontend/
│   │   ├── reactjs/
│   │   │   ├── react-component-design/
│   │   │   ├── react-state-management/
│   │   │   └── react-testing/
│   │   ├── nextjs/
│   │   │   ├── nextjs-app-router/
│   │   │   └── nextjs-data-fetching/
│   │   └── angular/
│   │       ├── angular-component-design/
│   │       └── angular-rxjs-state/
│   └── backend/
│       ├── dotnet/
│       │   ├── dotnet-api-design/
│       │   └── ef-core-data-access/
│       └── nodejs/
│           ├── nodejs-api-design/
│           └── nodejs-testing/
└── project/                        # Project-specific skills
    └── ptn/
        ├── ptn-project-conventions/
        └── ptn-change-verification/

Each skill is a directory containing SKILL.md. The directory name and frontmatter name must use the same lowercase, hyphenated value. Skill names must be unique across the catalog.

Add a skill

Run from the PersonalSkills repository in PowerShell:

Push-Location skills/common/frontend/nextjs
npx skills init nextjs-routing
Pop-Location

Push-Location enters the selected category and Pop-Location returns to the repository root. The npx skills init command only generates the new source SKILL.md in this catalog.

Example manifest:

---
name: nextjs-routing
description: Implement or review routing behavior in a Next.js application.
---

# Next.js Routing

Add focused instructions here.

Update a skill

Open and edit the source file:

skills/project/ptn/<skill>/SKILL.md

Then follow the validation and publishing steps below.

Move or rename a skill

git mv skills/<old-category>/<old-name> skills/<new-category>/<new-name>

Also update the name field inside SKILL.md when the directory name changes.

Delete a skill

git rm -r skills/<category>/<skill>

Validate and push catalog changes

npm run check
git add skills
git commit -m "Update skill catalog"
git push

After pushing, verify the remote catalog tree:

npx personal-skills list

Catalog-only changes do not require a new npm version or an npm publish.

Develop and publish the CLI

Use these commands only when the TypeScript CLI code or npm package configuration changes:

npm install
npm run dev
npm run check
npm publish --dry-run
npm publish

The prepublishOnly script runs type checking, tests, and a production build before publishing.