skills - Moses Yebei

The Problem

Coding agents like Claude Code, Codex, and Cursor each expect skills in their own directory layout, and teams want those skills committed per-project. Manually copying markdown skill files into every agent's directory — per project, per agent, per skill — is error-prone and doesn't scale. This CLI turns that into a single command.

What This Does

skills is a TypeScript CLI that fetches skill definitions from GitHub, GitLab, arbitrary git URLs, or local paths, and installs them into the correct agent directory. It supports project-scoped (default) or global (-g) installs, and symlink or copy modes. src/add.ts drives the add flow, src/installer.ts owns the filesystem work (symlinks, path safety, canonical directories), src/skills.ts discovers skills from a repo, and src/agents.ts detects which agents are installed.

How It Is Wired

Execution starts at main in src/cli.ts:553, which reaches 120 functions. It parses args, then dispatches to runAdd, runFind, runRemove, runCheck, or runUpdate. The add path flows through src/add.ts (21 functions, imports 12 modules — the highest instability at 0.73) into src/installer.ts for filesystem effects: symlink creation, directory cleanup, path validation. src/skill-lock.ts owns readSkillLock/writeSkillLock; readSkillLock is called from 11 places, the widest blast radius in the repo — change its signature and a dozen call sites break. src/agents.ts (Ca 8, Ce 1, instability 0.11) is the most stable hub; detectInstalledAgents is called from 6 places. One function calls a model for inference, via the HuggingFace provider. The module graph has 49 modules, 72 edges, and no circular dependencies — but the two oversized files (src/add.ts at 1,653 lines, src/installer.ts) concentrate most of the routing, so changes there ripple widely.

How To Use It

pnpm install
npx skills add vercel-labs/agent-skills

Target specific agents or skills:

npx skills add owner/repo --skill frontend-design -a claude-code -a opencode
npx skills add owner/repo --all -y

Sources include GitHub shorthand (owner/repo), full URLs, GitLab, git URLs, and local paths. Scope is project (./<agent>/skills/) or global (~/<agent>/skills/). No environment variables are required; configuration lives in package.json and tsconfig.json.

Real-World Use

A team standardizes on a shared skill repo. Each developer runs:

npx skills add team/agent-skills --skill "Convex Best Practices" -a claude-code

The skill lands in ./claude-code/skills/, is committed to the project, and is shared with the team — with --all -y for CI-friendly non-interactive installs.

Code Health & Issues

Static analysis found 9 findings (2 high, 7 medium):

High — Oversized files: src/add.ts and src/installer.ts (1,653 lines) are hard to hold in one head; split by responsibility.
High — Duplicated code: 40 repeated 6-line blocks across 12 files (src/add.ts, src/list.ts, their tests); extract shared helpers.
Medium — High branching density: 82 branch points over 206 lines in src/source-parser.ts, src/find.ts, src/plugin-manifest.ts; consider table/strategy dispatch.
Medium — Deep nesting: src/cli.ts reaches indentation depth 6; flatten with early returns.

SDLC observations: no LICENSE file at root (default is all rights reserved), agents.yml pushes to the default branch with no declared GITHUB_TOKEN permissions and no persist-credentials: false, no Dependabot, and no dependency vulnerability scan in CI. Tests and CI are present; no committed secrets found.

The Bottom Line

A well-structured CLI for a real pain point, with clean module boundaries and no circular dependencies — but the two core files carry too much weight and the automation workflow needs hardening before it's production-safe. Suitable for teams standardizing agent skills; add a license before redistributing.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

67 files

TypeScript47
YAML8
Markdown4
JSON2

ReactTransformers

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["src<br/>31 modules"] g1["tests<br/>12 modules"] g2["scripts<br/>4 modules"] g1 -->|11| g0 g2 -->|2| g0

Module dependencies

The 10 most depended-upon modules of 49, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_src_types["types"] n1_src_agents["agents"] n2_src_installer["installer"] n3_src_skills["skills"] n4_src_providers_types["types"] n5_src_test_utils["test-utils"] n6_src_add["add"] n7_src_source_parser["source-parser"] n8_src_skill_lock["skill-lock"] n9_src_telemetry["telemetry"] n6_src_add --> n7_src_source_parser n6_src_add --> n3_src_skills n6_src_add --> n2_src_installer n6_src_add --> n1_src_agents n6_src_add --> n9_src_telemetry n6_src_add --> n8_src_skill_lock n6_src_add --> n0_src_types n1_src_agents --> n0_src_types n2_src_installer --> n0_src_types n2_src_installer --> n1_src_agents n2_src_installer --> n3_src_skills n3_src_skills --> n0_src_types n7_src_source_parser --> n0_src_types

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium4

low1

Add a LICENSE; redistribution rights are undefinedhigh

no licence file at the repository root

Fix: Add MIT or Apache-2.0 at the repository root.

Open a pull request instead of pushing to the default branchhigh

.github/workflows/agents.yml

git push

Automated commits land on the branch that deploys, with no test having run against the result.

Fix: Push to a bot branch and open a pull request, or restrict the push to a tag ref.

Declare least-privilege permissions for GITHUB_TOKENmedium2 occurrences

.github/workflows/agents.yml

2 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

1 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/agents.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow3 occurrences

.github/workflows/agents.yml

3 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.