How Skills Auto-Load Based on Conversation Context vs. Forced Loading in pm-skills

The pm-skills framework supports two distinct loading mechanisms: automatic contextual loading that triggers when conversation text matches keywords in a skill's front-matter description field, and forced loading that executes immediately via slash commands like /skill-name or /plugin-name:skill-name.

The phuryn/pm-skills repository implements a dual-mode skill activation system that treats skills as nouns and concepts within AI conversations. This architecture allows Claude to surface relevant capabilities automatically based on discussion topics while preserving user control through explicit command syntax.

How Auto-Loading Works: Contextual Skill Detection

Front-Matter Description Triggers

The auto-loading mechanism relies entirely on front-matter metadata within each SKILL.md file. Specifically, the description field contains trigger phrases—keywords and concepts that the engine scans for during active conversations.

When a user mentions terms like "SWOT analysis" or "lean-canvas," the system matches these against the description fields of available skills. Upon detection, the skill loads into the UI with its short description displayed, ready for user invocation. According to CLAUDE.md#L48, this follows the rule that "Skills = nouns/concepts" and "Claude auto-loads when the topic matches (lean-canvas, pre-mortem, market-sizing)".

This trigger data resides in individual skill files such as pm-product-strategy/skills/swot-analysis/SKILL.md, where the front-matter defines the conceptual boundaries for automatic detection.

How Forced Loading Works: Explicit Slash Commands

Slash Command Syntax

Users can bypass contextual matching entirely through forced loading using slash commands. The syntax supports two distinct formats:

• /skill-name — Use when the skill name is unique across all installed plugins
• /plugin-name:skill-name — Use to disambiguate when multiple plugins contain identically named skills

As documented in CLAUDE.md#L55, "Skills can be force-loaded with /plugin-name:skill-name or /skill-name". This method instructs the system to pull the skill immediately regardless of the current conversation topic or detected keywords.

The command parser resolves these instructions by consulting the plugin manifest (plugin.json), which registers each available skill and its execution path.

Auto-Load vs. Forced Loading: Key Implementation Differences

The repository implements these as complementary trigger strategies:

Auto-Loading

• Trigger source: Conversation text containing keywords from the description field
• Definition location: SKILL.md front-matter (e.g., pm-product-strategy/skills/swot-analysis/SKILL.md)
• Behavior: Passive suggestion; surfaces the skill in the UI without immediate execution

Forced Loading

• Trigger source: Explicit user input via slash command syntax
• Resolution location: plugin.json manifest (command parser lookup)
• Behavior: Immediate execution; bypasses contextual scanning entirely

Practical Examples: Triggering Skills in Context

Consider the swot-analysis skill located at pm-product-strategy/skills/swot-analysis/SKILL.md:

Auto-loading scenario:

User: "I need a SWOT analysis for my new product."

Claude detects "SWOT" in the utterance, matches it to the swot-analysis skill's 
description field, and displays the skill card with its short description and 
available actions.

Forced loading scenario:

User: "/pm-product-strategy:swot-analysis"

Claude executes the skill immediately, bypassing contextual matching and loading 
the SWOT analysis framework directly.

Short-form forced loading (unique skill names):

User: "/swot-analysis"

Claude loads the skill directly using the unqualified command, resolved via 
the plugin.json manifest.

Summary

• Auto-loading scans conversation text against description fields in SKILL.md front-matter to suggest relevant skills passively when topics match.
• Forced loading uses slash commands (/skill-name or /plugin-name:skill-name) to execute skills immediately, resolved through the plugin.json manifest.
• The phuryn/pm-skills framework treats skills as nouns/concepts, enabling contextual surfacing while preserving explicit user control through command syntax.

Frequently Asked Questions

What file contains the trigger phrases for auto-loading?

The trigger phrases reside in the front-matter of each SKILL.md file, specifically within the description field. This metadata is visible to Claude for auto-loading purposes and is typically located at paths like pm-product-strategy/skills/swot-analysis/SKILL.md.

When should I use the /plugin-name:skill-name syntax instead of /skill-name?

Use the fully qualified /plugin-name:skill-name format when skill names might overlap across multiple plugins. The shorter /skill-name format works only when the skill name is unique across all installed plugins in the system.

How does the system resolve slash commands for forced loading?

The command parser consults the plugin manifest (plugin.json) to resolve skill references. This file registers each skill and its associated commands, enabling the system to locate and execute the correct skill when a user enters a slash command.

Does auto-loading execute skills automatically?

No, auto-loading only surfaces skills as suggestions in the UI. The skill appears with its short description and available actions, but requires explicit user confirmation to execute. Forced loading via slash commands represents the only method for immediate skill execution.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}