ProjectSkills CLI

Pull your project's Skills, Constitution and dependency graph into the repository, so the agent in your editor reads them from disk.

npm install -g projectskills

pskl login          # approve in the browser
pskl init           # create a project for this folder
pskl analyze --watch
pskl pull           # write .claude/skills/**/SKILL.md

Your code never needs to be on a public git host, and no GitHub App has to be installed. init and analyze work on the folder you are standing in — a private repository, or a directory with no git at all.

Commands

| | | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | pskl login | Connect this terminal. Shows a code, opens the browser, waits for approval. --token for CI. | | pskl logout | Remove the credential from this machine. | | pskl whoami | Who this terminal is signed in as, and on which plan. | | pskl init | Create a project for this directory and link it. --name, --analyze, -y. | | pskl link [project] | Bind the directory to a project that already exists. No argument lists them. | | pskl unlink | Remove the link from this directory. | | pskl status | Analysis state, model, snapshot, Skills and graph on one screen. | | pskl explain | A guided read of this codebase, for somebody who did not write it. --snapshot, --markdown. | | pskl pull | Write Skills and the Constitution. --out, --force, --prune, --for claude\|agents\|all. | | pskl mcp install | Write the MCP connection into this repo so an agent can ask, not only read. --for claude\|codex\|cursor\|all. No token in the file. | | pskl models | Which AI model analyses your projects, what each costs. --select, --set, --clear. | | pskl tree | The dependency tree. --depth. | | pskl graph summary | Size and readiness. Answers on every plan. | | pskl graph resolve <q> | Find node keys — needed before any traversal. | | pskl graph node <key> | One node, with neighbours and evidence. | | pskl graph community <n> | What is in one subsystem, with its cohesion. | | pskl graph export <fmt> | json, graphml or mermaid. | | pskl skills list | Every Skill, and which of them were requested. | | pskl skills freshness | Whether each Skill still describes the code. Names the source files that changed, and says when it cannot tell. | | pskl skills show <slug> | One Skill in full, with its review and provenance. --markdown for the document alone. | | pskl skills new "<subject>" | Ask for a Skill the analysis did not write. Premium. --detail. | | pskl skills regenerate [slug] | Rewrite a Skill against the current analysis. -y. | | pskl skills rm <slug> | Delete a Skill you requested. Catalogue Skills cannot be deleted. -y. | | pskl impact <node> | What breaks if this changes. --out inverts it, --depth, --limit. | | pskl why <a> <b> | How these two are connected. --max-hops, --undirected. | | pskl ask "<question>" | The part of the graph a question touches. --depth, --limit. | | pskl insights | Cycles, hubs and edges that should not exist. --limit. | | pskl diff | What changed in the graph between two snapshots. --from, --to, --list. | | pskl findings | What the deterministic detectors found, which of them actually ran, and what each one could not check. --severity, --category, --detector, --snapshot, --limit, --fail-on. | | pskl findings diff | Findings that are new, persisting or resolved between two snapshots. --base, --head, --fail-on, --markdown. | | pskl findings trend | Whether this project is getting better, across snapshots. A snapshot that was not fully checked is a break, not a low point. --limit. | | pskl findings hotspots | Files where findings, change and dependency land together. An unmeasured signal prints as unmeasured, never as zero. --snapshot, --limit. | | pskl snapshots | Every capture of this project: when it was taken, whether it was a commit or a working tree, and what it changed against the one before. | | pskl changes | Which files were added, modified, deleted or renamed in a snapshot — and which could not be compared at all. --snapshot, --kind, --limit. | | pskl intelligence | What the analysis concluded, every claim with its confidence. --section, --evidence, --snapshot. | | pskl sbom | A CycloneDX bill of materials. Built from manifests, never claims to be complete, and states no licence it does not know. --snapshot, --out. | | pskl share create | A read-only link to this snapshot's report, for somebody with no account. Shown once, expires. --days, --label, --snapshot. | | pskl share list | Every link, whether it is live, and how often it was opened. | | pskl share revoke <id> | Stop a link working, immediately. | | pskl webhooks list | Every destination registered, with what happened to the last delivery. | | pskl webhooks add <url> | Register a destination. https only, public address only; the signing secret is shown once. --events. | | pskl webhooks rm <id> | Stop delivering to a destination. | | pskl webhooks deliveries <id> | What happened to recent deliveries. REFUSED means this service declined to make the request, not that yours refused it. --limit. | | pskl stack | Technologies detected, and what each detection rests on. --category, --evidence. | | pskl architecture | The deterministic fact sheet — routes, tables, entry points, languages. --routes. | | pskl files | How the snapshot classified what it ingested, including anything classified secret. | | pskl usage | Tokens and cost for the month, by project, model and task. --project, --from, --to. | | pskl quota | How much of each limit is left, and when it resets. | | pskl history | Every analysis run, with cost, duration and what it produced. --limit, --status, --all. | | pskl keel start | Open a design session. --quadrant (FOUND · ORIGIN · FIT · CHART), -m. | | pskl keel say "<text>" | Send one turn and wait for the reply. --session. | | pskl keel show | Where the interview is, what it settled, and which model answered. --session. | | pskl keel list | Every session on this account. | | pskl keel skip <slot> | Record that nobody knows this yet — not the same as moving on. --session. | | pskl keel next | Close this stage and move on, whatever is still open. --session. | | pskl keel pull | Write KEEL.md, keel-session.md and keel-scaffold/. Premium. --out, --force, --session. | | pskl keel stale | Whether the plan is still true of the code it was written about. --session. | | pskl keel retry <kind> | Rebuild a plan or scaffold whose composition failed. Premium. --session. | | pskl keel abandon <id> | Close a session for good. The id is never resolved for you. | | pskl analyze | Start an analysis. --include-uncommitted, --allow-secrets, --github, --public, --zip, --watch. | | pskl analyze --local | Send a digest instead of the code: paths, sizes, hashes and dependency manifests. No source leaves the machine. Produces the file index, dependencies and SBOM — not the graph or the findings. | | pskl analyze status | The steps of the most recent run. --watch follows it. |

Exit codes

A tool that answers 1 for everything cannot be branched on in a script.

| | | | --- | --------------------------------------------- | | 0 | fine | | 1 | failed | | 2 | wrong usage | | 3 | not signed in | | 4 | plan does not include it | | 5 | not found | | 6 | rate limited | | 7 | not ready yet (no graph, analysis unfinished) |

Where things go

• .claude/skills/<name>/SKILL.md — the artefacts. The directory name must match the front-matter name: or Claude Code will not load them.
• .projectskills/project.json — the link. Commit it. A project id is not a secret: the API answers "not found" to anyone who is not a member.
• .projectskills/artifacts.json — what was written, and its hash. This is how pull knows not to overwrite a file you edited by hand.
• ~/.config/projectskills/credentials.json — the token, 0600.

PROJECTSKILLS_TOKEN overrides the stored credential and is never written to disk. That is the CI path.

Motion

analyze --watch paces a small robot along the line while the pipeline runs, captioned with the step it is on; uploads, packing and the sign-in wait get a spinner. All of it turns itself off when stdout is not a terminal, under --json, when CI is set, and on TERM=dumb — escape sequences in a log file are corruption, not decoration. The cursor is restored on exit and on Ctrl-C.

Notes

pskl analyze packs the current directory through git, so .gitignore is honoured by the same rules your own tooling uses — untracked node_modules and build output stay out.

.gitignore does not exclude a file git is already tracking. A .env committed before anyone thought to ignore it is still in your history, and would be uploaded. So before sending anything, analyze checks the archive against the same secret patterns the server uses and refuses, naming the files and how to untrack them. --allow-secrets overrides it.

• In a git repository it archives HEAD, so uncommitted work is excluded. It says how many changes it left behind.
• --include-uncommitted sends the working tree instead. Your staging area is never touched: it builds the tree through a throwaway index.
• A plain directory works too. No repository is needed — a temporary git directory is created outside your folder, and nothing is written into it.

pull never overwrites a generated file you have edited. It says which ones and exits non-zero; --force overrides.