---
name: add-resource-path-convention
description: Use when writing commands or skills that reference other commands, skills, or scripts — ensures paths resolve correctly across all providers after installation
---

# Resource Path Convention

Commands and skills in `framwork/.codeadd/` are the source of truth. After build, they are placed in provider-specific directories (`.claude/commands/`, `.agents/skills/`, `.gemini/commands/`, etc.). Hardcoded `.codeadd/commands/` or `.codeadd/skills/` paths break because these directories do not exist in the installed project. Use build-time variables to reference resources.

## When to Use

- Writing a command that references another command (e.g., autopilot loading add.plan)
- Writing a command or skill that references a skill file
- Reviewing existing commands/skills for broken path references
- Creating new commands via `/add.make`

## When NOT to Use

- Referencing scripts (`.codeadd/scripts/*.sh` is always correct — fixed path)
- Referencing project files outside the framework (`docs/`, `src/`, etc.)
- Writing code in `build.js` or `cli/` (these operate on the build/install pipeline, not agent runtime)

## Variables

Build-time variables are available. `build.js` replaces them with the correct provider path during build.

### `{{cmd:NAME}}`

Resolves to the full path of a command file for the target provider.

```
{{cmd:add.plan}}

# Claude → .claude/commands/add.plan.md
# Gemini → .gemini/commands/add.plan.toml
```

### `{{skill:NAME/FILE}}`

Resolves to the full path of a skill file. Use `SKILL.md` for the main file, or any sub-file name.

```
{{skill:add-backend-development/SKILL.md}}

# Claude → .claude/skills/add-backend-development/SKILL.md
# Gemini → .gemini/skills/add-backend-development/SKILL.md
```

### Scripts (no variable needed)

Scripts are always at `.codeadd/scripts/`. Use the literal path.

```
bash .codeadd/scripts/status.sh
bash .codeadd/scripts/done.sh
```

### `{{addpath:X}}`

Resolves to the literal `.codeadd/X` path — same across all providers. Use for **runtime paths** that exist in the user's installed project (the installer preserves `.codeadd/`), but are NOT distributed by the build pipeline.

Typical cases: skills generated at runtime by commands like `/add.xray` (which writes `project-patterns/`), the manifest file, or any artefact materialized in the user's project after install.

```
{{addpath:skills/project-patterns/backend.md}}  # → .codeadd/skills/project-patterns/backend.md
{{addpath:manifest.json}}                       # → .codeadd/manifest.json
```

**When to use `{{addpath:}}` vs `{{skill:}}`:**

| | `{{skill:NAME/FILE}}` | `{{addpath:skills/NAME/FILE}}` |
|---|---|---|
| Skill exists in `framwork/.codeadd/skills/` (source) | ✅ | ❌ |
| Skill is generated at runtime in user project | ❌ | ✅ |
| Resolves per-provider | ✅ | ❌ (always `.codeadd/`) |

## Examples

### Correct

```markdown
## STEP 1: Load Context
1. Read {{cmd:add.plan}} — PRIMARY reference
2. Run: bash .codeadd/scripts/status.sh
3. Read {{skill:add-backend-development/SKILL.md}}
4. For components, Grep {{skill:add-ux-design/shadcn-docs.md}}
```

### Incorrect

```markdown
## STEP 1: Load Context
Read .codeadd/commands/add.plan.md          ← BROKEN: doesn't exist after install
cat .codeadd/skills/backend-development/SKILL.md  ← BROKEN: wrong path
bash .codeadd/scripts/status.sh             ← CORRECT: scripts are at .codeadd/
```

## Validation Checklist

```
[ ] No raw references to .codeadd/commands/ (use {{cmd:NAME}})
[ ] No raw references to .codeadd/skills/ (use {{skill:NAME/FILE}} for source skills, {{addpath:skills/NAME/FILE}} for runtime-generated skills)
[ ] Script references use .codeadd/scripts/ (literal, no variable)
[ ] Runtime artefacts in installed project use {{addpath:X}}
[ ] Command names match provider-map.json commands keys
[ ] Skill names match provider-map.json skills keys (with add- prefix)
[ ] Skill sub-files exist in the source skill directory
```