Skills

A skill is a Markdown file that teaches an agent how to do something. The super-agent loads skills on demand — only the ones relevant to the current conversation. APX ships a set of bundled skills (skills/<slug>/SKILL.md in the package) and supports project-scoped and user-global custom skills.

Skills and agents are independent — an agent can reference skills by slug in its frontmatter, and the super-agent discovers them automatically from registered directories.

Where skills live

The super-agent’s own catalog (what it loads on demand, and what the web Skills manager shows) scans three locations, in priority order:

<project>/.apc/skills/<slug>/SKILL.md (or <slug>.md) — project-scoped (visible only in this project)
~/.apx/skills/<slug>/SKILL.md — user-global (all projects on this machine)
<APX package>/src/core/runtime-skills/<slug>/SKILL.md — built-in (ships with APX, immutable, always available; source "builtin")

The first match by slug wins. A project skill silently overrides a user-global or built-in skill with the same slug.

Install into IDE tools

Running apx skills add copies (or links) the bundled skills into your IDE’s rule files, so tools like Claude Code, Cursor, and Copilot pick them up automatically.

# Interactive: choose global or project scope
apx skills add

# Install to all global skill dirs (recommended for first setup)
apx skills add --global

# Install only to specific targets
apx skills add claude-code cursor

# Install project-scoped skills for specific targets
apx skills add windsurf copilot

IDE targets

Target ID	IDE	File written
`claude-code`	Claude Code	`.claude/skills/apx/SKILL.md`
`cursor`	Cursor	`.cursor/rules/apx.mdc`
`windsurf`	Windsurf	`.windsurf/rules/apx.md`
`copilot`	GitHub Copilot	`.github/copilot-instructions.md` (appended)
`trae`	Trae	`.trae/rules/project_rules.md` (appended)

Global installs write to ~/.claude/skills/, ~/.cursor/skills/, ~/.codex/skills/, and ~/.agents/skills/. These directories are read by Claude Code, Cursor, Codex (OpenAI), Antigravity, and any skills.sh-compatible tool.

Codex and Antigravity read AGENTS.md automatically — no separate install needed for those.

List and status

# List skills installed in this project's .apc/skills/
apx skills list

# List the full catalog (project + global + built-in), with on/off/private state
apx skills list --all

# Show which bundled skills are present in each global dir
apx skills status

apx

$ apx skills status
  Claude Code     ✓ installed       ~/.claude/skills/apx/SKILL.md
Cursor          ✓ installed       ~/.cursor/rules/apx.mdc
Windsurf        ✗ not installed   ~/.windsurf/rules/apx.md
Copilot         ✓ installed       ~/.github/copilot-instructions.md
Trae            ✗ not installed   ~/.trae/rules/apx.md

note: run apx skills add --global to install the missing targets

apx skills status showing installed and missing skills across global dirs

Sync bundled skills

After updating APX, re-sync the bundled skills to all global dirs:

apx skills sync

# Verbose — shows every (skill × target) line
apx skills sync --verbose

sync is idempotent and is also run automatically during npm install -g @agentprojectcontext/apx.

Manage skills from the web panel

The web admin panel has a Claude-Desktop-style Skills manager: a left list of installed skills plus a right viewer that renders the selected SKILL.md, with an Add dropdown (create online, upload a .zip, or import from a git repo) and a per-skill on/off switch.

You’ll find it in two places:

Settings → Agents → Skills (/settings/skills) — the global entry, with a scope picker (see below) and two inner tabs: Skills (the manager) and Config (RAG) (the Skill Inspector settings — thresholds, index status, and a prompt dry-run probe).
A project’s own Skills tab — the same manager embedded and locked to that project’s scope, so you can enable, disable, add, or inspect skills without leaving the project.

🖥️ SCREENSHOT · web Skills manager — installed skills list with source badges, and the SKILL.md viewer apx web, then Settings → Skills (or a project's Skills tab)

Skills manager — installed skills list with source badges, and the SKILL.md viewer

Scope-aware enable/disable

Any skill (except built-ins — see below) can be turned off per scope. A scope is either:

default — the super-agent / no-project baseline, labeled “Super-agent (global)” in the web picker, or
a specific project, keyed by its absolute path.

An explicit project-scope override wins over a default-scope override, which wins over the fallback (enabled). Toggling a skill off in one project does not affect any other project or the super-agent baseline unless you also toggle it there.

apx skills list --all   # STATE column shows on / off / private per this project's scope

Private built-in skills

Skills sourced from APX’s own built-in catalog (src/core/runtime-skills/, shown with source badge “APX”) are private: always active, and can never be disabled or deleted from any scope. The manager shows them with a lock icon and a disabled toggle. This guarantees APX’s own runtime knowledge (apx-*, apc-context, CLI-runtime docs) is always available regardless of what a user disables elsewhere. Skills sourced from ~/.apx/skills/ (source “Global”) or a project’s .apc/skills/ (source “Project”) are always toggleable and deletable.

The skills-stay-in-sync rule

AGENTS.md rule 6: when you change CLI commands, daemon routes, config keys, or any workflow documented in a skill, update the matching skills/<slug>/SKILL.md in the same commit. This keeps skills accurate as APX evolves.

Verify flags with apx <command> --help before documenting them — do not invent subcommands.

Write your own skill

A skill is a Markdown file with YAML frontmatter:

---
name: my-skill
description: When to load this skill — write it as a trigger condition, not a summary.
---

<!-- Body: concrete, opinionated, anti-example-driven. -->

The description field is what the model reads when deciding whether to call load_skill. Write it as a trigger: “Load BEFORE configuring X — covers Y and Z gotchas.”

Register a project skill

mkdir -p .apc/skills/my-skill
# write .apc/skills/my-skill/SKILL.md
apx skills list   # confirm it appears

No daemon restart needed — listSkills() re-scans on every call.