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 for the authoring guide.

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

CLI usage

List content

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

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

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

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:

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

--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:

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:

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:

   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 for the full authoring guide.