Apx Skill Builder

---
name: apx-skill-builder
scope: internal
description: Write a new APX skill — "creá una skill", "una skill nueva", "cómo se escribe una skill" — file location, frontmatter and body style. Load when creating or adding a skill to APX.
---

# apx-skill-builder

A **skill** is a Markdown file the super-agent loads on demand. Inspired by Anthropic's skill-creator, simplified for APX's daemon-served model.

## When to make a skill

- **Yes**: topic is bounded (a tool, a config domain, a recurring workflow), instructions need >50 tokens to be safe, not every conversation needs them.
- **No**: one-off explanations, casual chat, anything fitting in 2-3 lines of the base prompt.

## File location

Scanned in priority order:

1. `<repo>/.apc/skills/<slug>/SKILL.md` (or flat `<slug>.md`) — project-scoped.
2. `~/.apx/skills/<slug>/SKILL.md` — user-global.
3. `<packageRoot>/src/core/runtime-skills/<slug>/SKILL.md` — the runtime-internal set that ships with APX (the built-in `apx-*`, `apc-context`, `claude-code`, …). This is where a new super-agent skill goes.

> ⚠️ `<repo>/skills/` is **NOT** in the super-agent's load chain (see `src/core/agent/skills/loader.js:23`). That folder is the slim engine-side set replicated to external CLIs/IDEs (`~/.claude/skills/`, `~/.codex/skills/`). A skill authored there will never load for the super-agent — put it under `src/core/runtime-skills/`.

Layouts: `<slug>/SKILL.md` (dir-style, preferred — supports `references/`, `assets/`) or `<slug>.md` (flat, fine for short — project scope only).

## Frontmatter

```yaml
---
name: my-skill
description: One-sentence trigger for the super-agent. Include user-phrases that should cause it to load. Short — appears in skill listings.
scope: public   # public (synced globally) | internal (repo/dev-only) | optional (not pushed by default)
---
```

`description` is what the model sees when deciding `load_skill`. Write it as the *trigger condition*, not a body summary. Omit `scope` → treated as public.

**Good**: `"How to register an MCP server. Load BEFORE running 'apx mcp add' — three scopes, gotchas with stdio commands, secrets handling."`
**Bad**: `"This skill describes APX's MCP system."` (no trigger).

## Body style

Opinionated, concrete, anti-example-driven. Read a sibling `src/core/runtime-skills/apx-*` before writing yours. Shape:

1. **One-paragraph "what this is"** — no preamble.
2. **Concrete CLI calls** — most common first.
3. **Schema / shape** if files/config are involved.
4. **Anti-examples** — at least one "DON'T" with reason. Stops the model inventing flags.
5. **Open questions / footnotes** if the surface is incomplete.

Length budget: 80-200 lines. Longer → split or move scripts to `<slug>/scripts/`.

## Loader + commands

```js
// Model emits:
load_skill({ slug: "my-skill", project_path: "/abs/path/optional" })
```

Returns the full body for the current turn; not persisted.

```bash
apx skills list          # this project's .apc/skills/ (run from project root)
apx skills sync          # push bundled/public skills to global skill dir
apx skills status        # what's installed vs available
```

## Workflow

```bash
# 1. Pick scope:
#    .apc/skills/<slug>/SKILL.md                     (project)
#    ~/.apx/skills/<slug>/SKILL.md                   (user-global)
#    src/core/runtime-skills/<slug>/SKILL.md         (runtime-internal, ships with APX)

# 2. Write
mkdir -p src/core/runtime-skills/my-thing
$EDITOR src/core/runtime-skills/my-thing/SKILL.md

# 3. Verify (daemon picks up on next listSkills() — no restart)
apx skills list | grep my-thing

# 4. Pre-test with the super-agent (default target)
apx exec "Load the my-thing skill and summarize it in 3 bullets"
```

## Anti-examples

```yaml
---
# DON'T omit description — the model can't trigger on slug alone.
name: vague-stuff
---

# DON'T pile general advice. ONE topic per skill. A grab-bag is dead weight.

# DON'T duplicate apx --help. Skills explain WHEN and WHY, not WHAT.
# Teach the decision tree ("shared vs runtime", "what to do if it fails").

# DON'T leave TODOs in production skills. Delete incomplete sections;
# move them to spec/active/backlog/ (local-only).
```

## Optional scaffolding

```
src/core/runtime-skills/my-thing/
├── SKILL.md           ← always
├── references/        ← markdown the skill cites
├── assets/            ← images, schemas, sample inputs
└── scripts/           ← shell/node helpers the skill shells out to
```

Only `SKILL.md` is auto-loaded. Reference others by relative path from the body ("see references/examples.md").

## Existing skills — mimic the style

`src/core/runtime-skills/apx-routine`, `apx-mcp`, `apx-integrations`, `apx-task`, `apx-telegram`, `apx-runtime`, `apx-sessions`, `apx-voice`, `apx-agent`, `apx-project`. Pick the closest topic, copy the structure.

## Maintainer contract

The dev guide `AGENTS.md` (repo root) rule 6 requires skills to move in lockstep with feature changes. Update or add the skill in the same PR as the behavior change — especially `src/core/runtime-skills/apx-*`.

## Don't

- Don't ship without frontmatter `description` — loader works, trigger is silent.
- Don't put secrets inside skills. They're read aloud by an LLM.
- Don't reference machine-only paths — use `<repo>` or `~/.apx` placeholders.
- Don't write in third person. The reader is the model. Write to it.