# Quickstart

Get from clone to a working skill in under 5 minutes.

## Prerequisites

- **Node.js 18+** for the `gskp` npm CLI and package build
- **bash** shell (macOS, Linux, or WSL on Windows) for `scripts/pack.sh` and remaining shell-backed `gskp` commands
- **jq** for git-checkout `scripts/pack.sh` write commands and `gskp install-deck` materialization: `brew install jq` (macOS) or `apt install jq` (Debian/Ubuntu). Node-owned `gskp install`, `remove`, `refresh`, `doctor`, `prune`, `pin`, `unpin`, `status`, `list-packs`, `set-mode`, and `set-update-mode` do not require `jq`
- **Claude Code** or **OpenAI Codex** installed on your machine
- **pnpm** (optional, for running tests): `npm install -g pnpm`

## 1. Choose an Install Path

### Source checkout

Use the source checkout when you are developing this repository or installing base skills from a local clone:

```bash
git clone <this-repo-url> ~/agentic-skills
cd ~/my-project
npx skillpacks init
```

`npx skillpacks init` installs repo-managed base skill directories **project-local** into the current repository's `.claude/skills/` and `.codex/skills/` roots and records `base_skills: true` in `.agents/project.json`. Track-latest installs are managed copies with drift metadata; pinned archived skills are the symlink case. Domain packs are not installed as base skills — that is intentional context hygiene.

### npm CLI

With the published npm package, use `npx skillpacks` from the project that should receive local skills:

```bash
cd ~/my-project
npx skillpacks --version
npx skillpacks init
npx skillpacks list
```

The npm CLI installs base skills **project-local only** — there is no user-home (global) install path. `npx skillpacks init` installs base skills into the current repository's local `.claude/skills/` and `.codex/skills/` roots and records `base_skills: true` in `.agents/project.json`. Later `npx skillpacks refresh` updates those base skills from the package snapshot being run. To clean up legacy user-home base installs from the retired init path, run `npx skillpacks uninstall-global`. Domain packs are never installed as base skills.

The scoped alias package is published from the same release artifact and version. Users who prefer that package identity can run `npx @glexcorp/gskp init`, `npx @glexcorp/gskp install devtool`, and the same subcommands.

## 2. Install a Pack in Your Project

Navigate to any project repository and install the pack that matches your domain:

```bash
cd ~/my-project
npx skillpacks init
npx skillpacks install devtool    # for developer tools
npx skillpacks install game        # for games
npx skillpacks install business-discovery  # for SaaS/business apps
```

From a source checkout, the equivalent compatibility route is:

```bash
~/agentic-skills/scripts/pack.sh install devtool
```

This creates `.agents/project.json` and project-local skill roots in `.claude/skills/` and `.codex/skills/`. `init` is the base-skill step; `install` is the domain-pack or individual-pack-skill step.

The npm CLI can also install a canonical deck from manifest metadata:

```bash
npx skillpacks install-deck business-afps
npx skillpacks install-deck devtool-afps
npx skillpacks install-deck game-afps
```

## 3. Reload Skills in Your CLI

Skills are not hot-reloaded. After installing:

- **Claude Code:** run `/reload-skills`, then `/clear` or restart the session. If `.claude/skills/` did not exist when the session started, restart Claude Code entirely.
- **Codex:** start a fresh Codex CLI session.

## 4. Verify the Installation

Source checkout:

```bash
~/agentic-skills/scripts/pack.sh status
```

npm:

```bash
npx skillpacks status
```

Or from within Claude Code: run `/pack` with no arguments. From Codex: run `$pack`.

## 5. Run Your First Skill

The AFPS (Alignment First, Prototype Second) workflow is the default product workflow. A typical first cycle:

**Claude Code:**
```
/codebase-status          # see what you're working with
/idea-scope-brief         # shape a rough idea into a scoped brief
```

**Codex:**
```
$codebase-status
$idea-scope-brief
```

For projects with an existing `tasks/todo.md`:
```
/exec                     # execute the next planned step
```

## 6. Confirm It Worked

After running a skill, look for these artifacts:

- `tasks/todo.md` — updated task list
- `tasks/history.md` — shipped work log entry
- A git commit with the skill's output
- An alignment page in `alignment/` (for research skills)

Alignment maintenance from npm is available through:

```bash
npx skillpacks alignment bundles --check
npx skillpacks alignment pages audit
npx skillpacks alignment pages inject-tts --force alignment/example.html
```

From a source checkout, the direct script paths remain canonical: `node scripts/upgrade-alignment-page.mjs`, `node scripts/audit-alignment-pages.mjs`, and `node scripts/inject-tts.mjs`.

## Migration Notes

Moving from a source checkout to npm does not change the project-local files. From the target project directory, run the npm command that matches your existing pack designation:

```bash
npx skillpacks refresh
npx skillpacks doctor
```

`skillpacks@<semver>` selects the package snapshot. Skill pins remain skill-level pins, for example `npx skillpacks pin quality-sweep v0.0`. If a pinned archive version is not present in the installed npm package, upgrade the npm package or use a source checkout that contains that archive.

## What's Next

- Run `/skills` or `$skills` to browse all available skills
- See [pack-workflow-matrix.md](pack-workflow-matrix.md) for workflow ordering and dependencies
- See [skill-anatomy.md](skill-anatomy.md) to understand or create skills
- See [troubleshooting.md](troubleshooting.md) if something goes wrong
