resolve-content

Files (2)

• SKILL.md
• resolve-content.js

SKILL.md (first lines)

# Resolve Content

This is an **Action** skill — a single, deterministic resolution step. Given a human reference, it returns the UUIDs the other actions require.

## Why this exists

Every read/update action needs UUIDs (`courseId`, `lessonId`, `topicId`), but users refer to content by **title** or **admin URL**. There is **no server-side title/slug search** on the catalog API, so previously the only way to get IDs was to manually walk `list-course-groups` → `get-course-structure`. This action does that resolution for you.

## When to use

- Before `get-full-content`, `get-course-structure`, `get-topic`, `get-topics-by-lesson`, or `update-course-content` when you have a **title/URL/slug** but not a UUID.
- Any time the user says "lesson X of course Y" without giving IDs.

## What it does

1. **Course group / course:**
   - UUID → used directly (tries course-group id first for `displayCourseId`, else treats it as a course id).
   - URL → extracts a UUID and/or slug from the path.
   - Title/slug → paginates `GET /courseGroups` and matches case-insensitively (exact title/slug first, then substring).
2. Derives the **`courseId`** (`displayCourseId`) for the matched group.
3. If `--lesson`/`--topic` are given, fetches `GET /courses/{courseId}/structure` and matches the lesson/topic by title (or UUID).

## Agent instructions

1. Pass the user's reference as `--course=` (and optionally `--lesson=` / `--topic=`).
2. Read the JSON result:
   - `resolved: true` → use `ids.courseId`, `ids.lessonId`, `ids.topics[].id`, etc.
   - `candidates` present → the reference was ambiguous. **Show the candidates and ask the user to pick — never invent or guess a UUID.**
   - `resolved: false` with no candidates → nothing matched; tell the user and offer to browse `list-course-groups`.
3. Then run the real read/update action with the resolved IDs (e.g. `get-full-content --id=<courseId>`).

## Run the script

```bash
node "${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/actions/resolve-content/}resolve-content.js" --course="Course Title"
node "${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/actions/resolve-content/}resolve-content.js" --course="Course Title" --lesson="Lesson Name" --topic="Topic Name"
node "${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/actions/resolve-content/}resolve-content.js" --course="https://acme.thoughtindustries.com/learn/course/my-course-slug"
node "${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/actions/resolve-content/}resolve-content.js" --course=COURSE_GROUP_OR_COURSE_UUID
```

## Notes & limits

- The catalog has no search endpoint, so a title/slug lookup paginates (up to `--max-pages` × 1000 groups, default 20). If the course isn't found and the result says the catalog wasn't fully scanned, increase `--max-pages`. A UUID or URL-with-UUID resolves instantly without scanning.
- Matching is case-insensitive; ambiguous matches are returned as `candidates` rather than guessed.
- **Single-page kinds:** when the matched group's `kind` is `article` or `video`, the content is single-page (no section/lesson/topic tree). Read its body the same way — pass the resolved `courseId` to **`get-full-content`**, which auto-detects the single-page case (or force it with `--kind=article|video`).

<HARD-GATE>
Read-only. This action never modifies, creates, deletes, or publishes content — it only resolves identifiers.
</HARD-GATE>

From thoughtindustries/ti-admin-plugin, MIT.

More from thoughtindustries/ti-admin-plugin