lw-lms-abilities

Consumer and reviewer reference for LW LMS 2.0.1 Abilities API registrations. Use when calling or auditing `lw-lms/list-courses`, `lw-lms/get-course`, `lw-lms/get-progress`, `lw-lms/set-progress`, `lw

SKILL.md

GitHub

LW LMS Abilities API

Use this when an AI agent, MCP client, REST consumer, or reviewer works with the machine-callable lw-lms/* abilities. This is not the learner-facing /wp-json/lms/v1 REST API and not the companion-plugin extension hook map; it is the admin/agent-facing ability surface.

When to use this skill

Trigger this skill when ANY of the following is true:

  • The request mentions lw-lms/list-courses, lw-lms/get-course, lw-lms/get-progress, lw-lms/set-progress, or lw-lms/get-options.
  • Code calls /wp-json/wp-abilities/v1/abilities/lw-lms/.../run.
  • A user asks how an automation agent or MCP client can inspect or mutate LMS course/progress data.
  • A diff touches includes/SiteManager/Integration.php, includes/SiteManager/Abilities/, OutputSchemas, or the ability service classes.
  • You need to decide whether to call Abilities API vs /wp-json/lms/v1.

Verified registration model

LW LMS 2.0.1 registers the same five abilities in two modes. The quiz, drip, React admin, and privacy releases did not add abilities. They did tighten progress authorization and validation. Version 2.0.1 adds explicit MCP-public metadata so Site Manager can discover the foreign lw-lms/* namespace.

  1. Site Manager bridge: hooks lw_site_manager_register_categories and lw_site_manager_register_abilities, receives the Site Manager PermissionManager, and registers into category lms.
  2. Standalone fallback: hooks wp_abilities_api_categories_init and wp_abilities_api_init at priority 20. did_action() guards prevent duplicate registration when Site Manager is active.

Do not claim Site Manager is required for LMS abilities. Since v1.2.16, WordPress 6.9+ Abilities API or the feature plugin is enough.

MCP visibility

Each ability now carries:

'mcp' => [
    'public' => true,
    'type'   => 'tool',
],

With LW Site Manager 1.5.1, all five lw-lms/* abilities appear in its discovery response. MCP visibility does not bypass the ability permission callback or the target-object checks.

Ability catalog

Ability Type Permission key Input Output
lw-lms/list-courses readonly can_edit_posts per_page, page success, courses, total, total_pages, page, per_page
lw-lms/get-course readonly can_edit_posts required course_id success, course with sections and lessons
lw-lms/get-progress readonly can_manage_lms required user_id, course_id summary plus lesson status map
lw-lms/set-progress write can_manage_lms required user_id, course_id, lesson_id, status success, message
lw-lms/get-options readonly can_manage_options empty object success, options

set-progress accepts only completed, in_progress, or not_started. Reverting from completed is a write that loses the completion timestamp for that row; do not treat it as harmless even though AbilityMeta::write() marks writes idempotent.

Calling pattern

Abilities use the core Abilities API route, not the LMS REST namespace:

curl -X POST "${SITE_URL}/wp-json/wp-abilities/v1/abilities/lw-lms/get-progress/run" \
  -u 'admin:xxxx xxxx xxxx xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"user_id":7,"course_id":42}}'

The request body must wrap arguments in input. Direct PHP is also valid:

$ability = wp_get_ability( 'lw-lms/set-progress' );
$result  = $ability->execute(
    [
        'user_id'   => 7,
        'course_id' => 42,
        'lesson_id' => 55,
        'status'    => 'completed',
    ]
);

Critical rules

  • Use Abilities API for admin/agent operations; use /wp-json/lms/v1 for learner-facing frontend data.
  • Feature-detect with function_exists( 'wp_register_ability' ) or wp_get_ability( 'lw-lms/list-courses' ); the plugin silently skips abilities when the API is unavailable.
  • Course abilities continue to use can_edit_posts; options use can_manage_options. Progress abilities use the LMS-specific can_manage_lms, resolved directly as manage_lms || manage_options even when Site Manager is present.
  • lw-lms/get-course returns admin/agent data, not access-gated learner content. Do not expose it directly to public learners.
  • get-progress rejects missing users and non-course posts. set-progress also verifies that the lesson exists and belongs to the supplied course.
  • lw-lms/set-progress calls ProgressRepository::upsert(), so completion hooks, snapshots, and drip-cache invalidation still run. It is an administrative override of learner quiz and drip gates; do not replace it with raw SQL.
  • Trust OutputSchemas over the older prose docs when shape details differ; v1.2.16 added total_pages, page, and per_page to list-courses.

Common mistakes

# WRONG: LMS learner REST namespace, not an ability run route.
curl -X POST "${SITE_URL}/wp-json/lms/v1/get-progress"

# RIGHT:
curl -X POST "${SITE_URL}/wp-json/wp-abilities/v1/abilities/lw-lms/get-progress/run" \
  -d '{"input":{"user_id":7,"course_id":42}}'
// WRONG: assume Site Manager must be active.
if ( ! class_exists( '\LightweightPlugins\SiteManager\Plugin' ) ) {
    return;
}

// RIGHT: check the ability/API you actually need.
if ( function_exists( 'wp_get_ability' ) && wp_get_ability( 'lw-lms/list-courses' ) ) {
    // Call it.
}

Cross-references

  • Run lw-lms-backend-extend when adding companion hooks around enrollment, access, or progress.
  • Run lw-site-manager-overview when consuming the broader site-manager/* ability surface.
  • Run wp-abilities-api for the underlying WordPress Abilities API mechanics.

What this skill does NOT cover

  • Public learner UI and course rendering. Use lw-lms-rest-frontend for the core REST API contract.
  • Registering arbitrary third-party Site Manager abilities. Use lw-site-manager-extend-abilities.
  • LearnDash migration. Use lw-lms-learndash-migration.

References

  • Registration bridge and fallback: includes/SiteManager/Integration.php.
  • Ability definitions: includes/SiteManager/Abilities/CourseAbilities.php, ProgressAbilities.php, OptionsAbilities.php.
  • Permission fallback: includes/SiteManager/Abilities/AbilityPermissions.php.
  • Output schemas: includes/SiteManager/Schema/OutputSchemas.php.
  • Service behavior and WP_Error codes: includes/SiteManager/Service/.
  • Official documentation: https://github.com/lwplugins/lw-lms
  • Official documentation: https://developer.wordpress.org/apis/abilities-api/
  • Verified source paths:
    • includes/SiteManager/Abilities/AbilityMeta.php
    • docs/site-manager-abilities.md