npm package: @phylax-systems/skills
Description: Installable agent skills, multi-step workflows, and reusable role definitions for Claude Code, Codex, and OpenCode. Ships as a small npm CLI that installs bundled content into each agent's home directory.
Latest version: 0.1.3

# agentic-engineering

Installable agent skills, multi-step workflows, and reusable role definitions for Claude Code, Codex, and OpenCode. Ships as a small npm CLI that installs bundled content into each agent's home directory.

## Project structure

```
skills/          Installable skill prompts (each has a SKILL.md marker)
workflows/       Multi-step orchestrated processes (each has a WORKFLOW.md marker)
agents/          Reusable agent role definitions (planner, implementer, reviewer)
src/             CLI and installer helpers
scripts/         Manifest generator
docs/            Supplementary documentation
mcps/            MCP server sources
```

## Concepts

**Skills** are self-contained prompt files that teach an agent how to handle a specific kind of work (e.g. Rust development, bug fixing, code review). Each skill directory contains a `SKILL.md` with frontmatter and instructions, plus optional `references/` for supporting material.

**Agents** are reusable role definitions (planner, implementer, reviewer) that describe how an agent should behave. Workflows reference agents by name to assign responsibilities to each step.

**Workflows** are multi-step orchestrated processes that compose agents and skills into a repeatable delivery pipeline with human gates and state tracking. A workflow defines steps, assigns agents and skills to each step, and specifies where human approval is required. See [`workflows/README.md`](workflows/README.md) for the authoring guide.

Skills and agents are the building blocks; workflows compose them into end-to-end processes.

## CLI usage

### List content

```bash
npx @phylax-systems/skills list              # list published skills
npx @phylax-systems/skills list workflows    # list published workflows
npx @phylax-systems/skills list agents       # list published agents
```

### Install skills

```bash
npx @phylax-systems/skills install rust          # install one skill
npx @phylax-systems/skills install all           # install every skill
npx @phylax-systems/skills install               # interactive skill picker
npx @phylax-systems/skills add rust              # "add" is an alias for "install"
```

### Install workflows

```bash
npx @phylax-systems/skills install workflow plan-implement-review   # install one workflow
npx @phylax-systems/skills install workflow all                     # install every workflow
npx @phylax-systems/skills install workflow                         # interactive workflow picker
```

### Install agents

```bash
npx @phylax-systems/skills install agent planner          # install one agent role
npx @phylax-systems/skills install agent all              # install every agent role
npx @phylax-systems/skills install agent                  # interactive agent-role picker
npx @phylax-systems/skills install everything             # install skills, workflows, and agents
```

### Target specific agents

By default the installer writes to all supported agent directories. Target a subset with `--agent`:

```bash
npx @phylax-systems/skills install rust --agent claude-code --agent codex
```

Accepted agent names: `claude-code` (or `claude`), `codex`, `opencode`.

### Install paths

Skills install to:

- Claude Code: `~/.claude/skills/<name>/`
- Codex: `$CODEX_HOME/skills/<name>/` (defaults to `~/.codex/skills/<name>/`)
- OpenCode: `~/.config/opencode/skills/<name>/`

Workflows install to the same roots under `workflows/` instead of `skills/`:

- Claude Code: `~/.claude/workflows/<name>/`
- Codex: `$CODEX_HOME/workflows/<name>/` (defaults to `~/.codex/workflows/<name>/`)
- OpenCode: `~/.config/opencode/workflows/<name>/`

Agents install to the same roots under `agents/` instead of `skills/`:

- Claude Code: `~/.claude/agents/<name>/`
- Codex: `$CODEX_HOME/agents/<name>/` (defaults to `~/.codex/agents/<name>/`)
- OpenCode: `~/.config/opencode/agents/<name>/`

### Optional flags

```bash
--force            Overwrite existing installation
--dir <path>       Override home directory root (for development/testing)
```

## Local development

Generate the manifest, run tests, and smoke-test the CLI:

```bash
npm run build:manifest
npm test
node src/cli.mjs list
node src/cli.mjs list workflows
```

`npm test` verifies the installer package itself, including packing the npm tarball, installing that tarball into a temporary consumer project, and checking that `install everything` reproduces every bundled file for Codex.

Test agent-specific installs against a temporary home directory:

```bash
node src/cli.mjs add rust --agent codex --dir /tmp/skills-home
node src/cli.mjs install workflow plan-implement-review --agent claude-code --dir /tmp/skills-home
node src/cli.mjs install agent planner --agent codex --dir /tmp/skills-home
node src/cli.mjs install everything --agent codex --dir /tmp/skills-home
```

The manifest generator (`scripts/generate-manifest.mjs`) scans `skills/`, `workflows/`, and `agents/` for installable content. Skills and workflows use directory markers (`SKILL.md`, `WORKFLOW.md`); agents support both single-file markdown definitions in `agents/*.md` and directory-based roles containing `AGENT.md` or `AGENTS.md`. The generator writes the packaged manifest to `src/manifest.json`.

## Publishing

The npm package includes the installer, published `skills/`, `workflows/`, and `agents/` content, so installs do not depend on GitHub availability at runtime.

1. Update content in `skills/`, `workflows/`, or `agents/`.
2. Run `npm run build:manifest`.
3. Run `npm test`.
4. Optionally inspect the exact tarball contents with `NPM_CONFIG_CACHE=/tmp/npm-cache-agentic-engineering npm pack --dry-run --json`.
5. Make sure the publishing npm account can write to the `@phylax-systems` scope. The `phylax-systems` npm organization must exist and your account must be a member with publish permissions.
6. Publish with `npm publish`. The package sets `publishConfig.access=public`.
7. If your local npm cache has permission issues:
   ```bash
   NPM_CONFIG_CACHE=/tmp/npm-cache-agentic-engineering npm publish
   ```

## Authoring new content

- **Skills**: create a directory under `skills/` with a `SKILL.md` containing YAML frontmatter (`name`, `description`). Add optional `references/` for supporting material.
- **Agents**: create either a top-level markdown file in `agents/` (for example `agents/ui-audit.md`) or a directory under `agents/` with an `AGENT.md` (or `AGENTS.md`) containing YAML frontmatter (`name`, `description`).
- **Workflows**: see [`workflows/README.md`](workflows/README.md) for the full authoring guide.