Rewrite skill descriptions to follow best practices (#90) (#92)

- Use third-person voice instead of "This skill should be used when..."
- Lead with what the skill does, then when to use it
- Remove bloated quoted trigger-phrase lists
- Standardize YAML block scalar to >- across all skills
- Bump plugin version to 1.2.2

Co-authored-by: Priyanshu Agrawal <priyanshuag@Priyanshus-MacBook-Pro.local>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 3 people

plugins/power-pages/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "power-pages",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Create and deploy Power Pages sites using modern development approaches. Supports code sites (SPAs) with React, Angular, Vue, or Astro, with more site types coming soon.",
   "author": {
     "name": "Microsoft",

plugins/power-pages/skills/activate-site/SKILL.md

@@ -1,11 +1,9 @@
 ---
 name: activate-site
-description: >
-  This skill should be used when the user asks to "activate site",
-  "provision website", "activate a Power Pages website", "activate portal",
-  "provision portal", "turn on my site", "enable website",
-  or wants to activate/provision a Power Pages website in their
-  Power Platform environment via the Power Platform REST API.
+description: >-
+  Activates and provisions a Power Pages website in a Power Platform environment
+  via the Power Platform REST API. Use when the user wants to activate, provision,
+  turn on, or enable a Power Pages website or portal.
 user-invocable: true
 allowed-tools: Read, Bash, Glob, Grep, AskUserQuestion, TaskCreate, TaskUpdate, TaskList
 model: sonnet

plugins/power-pages/skills/add-cloud-flow/SKILL.md

@@ -1,16 +1,11 @@
 ---
 name: add-cloud-flow
-description: >
-  Use this skill when the user wants to "add a cloud flow", "connect a Power Automate flow",
-  "register a flow", "link a flow to the site", "add automation", "integrate a flow",
-  "wire up a Power Automate workflow", "use this flow on another page", "add the flow to the
-  support page too", or wants to allow site users to trigger one or more Power Automate cloud
-  flows from a Power Pages site. This skill lists available flows (including already-registered
-  ones that can be integrated into additional pages), suggests the most relevant flows based on
-  the user's intent, identifies scenarios and web roles, creates the metadata files, generates
-  client-side code to call the flows, and presents an HTML plan showing roles and reasoning
-  for each flow. Already-registered flows can be selected for frontend-only integration into
-  new pages or components without re-creating metadata.
+description: >-
+  Integrates Power Automate cloud flows into a Power Pages site. Lists available flows,
+  suggests relevant ones based on intent, identifies scenarios and web roles, creates metadata
+  files, and generates client-side code to call flows. Handles both new flow registration and
+  adding already-registered flows to additional pages without re-creating metadata. Use when
+  the user wants to add, connect, register, or link a Power Automate cloud flow to their site.
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion, Skill, Task, TaskCreate, TaskUpdate, TaskList
 model: opus

plugins/power-pages/skills/add-sample-data/SKILL.md

@@ -1,11 +1,9 @@
 ---
 name: add-sample-data
-description: >
-  This skill should be used when the user asks to "add sample data",
-  "populate tables", "seed data", "add test records", "generate sample records",
-  "insert demo data", "fill tables with data", "create test data",
-  or wants to populate their Dataverse tables with sample records
-  so they can test and demo their Power Pages site.
+description: >-
+  Populates Dataverse tables with sample records for testing and demoing a Power Pages site.
+  Use when the user wants to add sample data, seed data, generate test records, or insert
+  demo data into their tables.
 user-invocable: true
 allowed-tools: Read, Write, Bash, Grep, Glob, AskUserQuestion, Task, TaskCreate, TaskUpdate, TaskList, mcp__plugin_power-pages_microsoft-learn__microsoft_docs_search, mcp__plugin_power-pages_microsoft-learn__microsoft_code_sample_search, mcp__plugin_power-pages_microsoft-learn__microsoft_docs_fetch
 model: sonnet

plugins/power-pages/skills/add-seo/SKILL.md

@@ -1,11 +1,9 @@
 ---
 name: add-seo
-description: >
-  This skill should be used when the user asks to "add SEO", "add meta tags",
-  "add robots.txt", "add sitemap", "improve SEO", "search engine optimization",
-  "add open graph tags", "add favicon", "make site searchable",
-  or wants to add SEO essentials (robots.txt, sitemap.xml, meta tags) to their
-  Power Pages code site after creating it with /create-site.
+description: >-
+  Adds SEO essentials to a Power Pages code site, including robots.txt, sitemap.xml,
+  meta tags, Open Graph tags, and favicon configuration. Use when the user wants to
+  improve search engine optimization or make their site more searchable.
 user-invocable: true
 allowed-tools: Read, Write, Edit, Grep, Glob, Bash, AskUserQuestion, Task, TaskCreate, TaskUpdate, TaskList, mcp__plugin_power-pages_playwright__browser_navigate, mcp__plugin_power-pages_playwright__browser_snapshot, mcp__plugin_power-pages_playwright__browser_click, mcp__plugin_power-pages_playwright__browser_close
 model: sonnet

plugins/power-pages/skills/add-server-logic/SKILL.md

@@ -1,15 +1,11 @@
 ---
 name: add-server-logic
-description: >
-  This skill should be used when the user asks to "create server logic", "add server-side code",
-  "write server logic", "add server endpoint", "create API endpoint", "add backend logic",
-  "write server-side JavaScript", "integrate server logic", "add server logic function",
-  "add server-side processing", "create serverlogic", "add serverlogics", or wants to create,
-  edit, or manage Power Pages Server Logic files — server-side JavaScript that runs securely
-  on the Power Pages runtime. This skill orchestrates the full lifecycle: understanding
-  requirements, fetching latest documentation, implementing the server logic code, configuring
-  site settings, and deploying. Use this skill whenever the user mentions "server logic",
-  "server-side code", or wants to move logic from the browser to the server in their Power Pages site.
+description: >-
+  Creates, edits, and manages Power Pages Server Logic files — server-side JavaScript that
+  runs securely on the Power Pages runtime. Orchestrates the full lifecycle: gathering
+  requirements, fetching documentation, implementing code, configuring site settings, and
+  deploying. Use when the user wants to add server-side code, create API endpoints, or move
+  logic from the browser to the server in their Power Pages site.
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion, Skill, Task, TaskCreate, TaskUpdate, TaskList, mcp__plugin_power-pages_microsoft-learn__microsoft_docs_search, mcp__plugin_power-pages_microsoft-learn__microsoft_code_sample_search, mcp__plugin_power-pages_microsoft-learn__microsoft_docs_fetch
 model: opus

plugins/power-pages/skills/audit-permissions/SKILL.md

@@ -1,13 +1,10 @@
 ---
 name: audit-permissions
 description: >-
-  Use this skill to audit existing table permissions on a Power Pages site.
-  Trigger examples: "audit permissions", "check permissions", "review table permissions",
-  "are my permissions correct", "permission security audit", "verify permissions setup",
-  "check for permission issues", "permission health check".
-  This skill analyzes existing table permissions against the site code and Dataverse metadata,
-  generates an HTML audit report with findings grouped by severity (critical, warning, info, pass),
-  and suggests fixes for any issues found.
+  Audits existing table permissions on a Power Pages site by analyzing them against site code
+  and Dataverse metadata. Generates an HTML audit report with findings grouped by severity
+  (critical, warning, info, pass) and suggests fixes for issues found. Use when the user wants
+  to review, verify, or check table permissions for security issues.
 user-invocable: true
 argument-hint: "[optional: specific table or concern]"
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, TaskCreate, TaskUpdate, TaskList, Agent

plugins/power-pages/skills/create-site/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: create-site
-description: This skill should be used when the user asks to "create a power pages site", "build a code site", "scaffold a website", "create a portal", "make a new site", or wants to create a new Power Pages code site (SPA) using React, Angular, Vue, or Astro.
+description: >-
+  Creates a new Power Pages code site (SPA) using React, Angular, Vue, or Astro. Guides through
+  the full process from initial concept to deployed site: requirements discovery, scaffolding,
+  component planning, design, implementation, validation, and deployment. Use when the user
+  wants to create, build, or scaffold a new Power Pages website or portal.
 user-invocable: true
 argument-hint: Optional site description
 allowed-tools: Read, Write, Edit, Grep, Glob, Bash, WebSearch, AskUserQuestion, Task, TaskCreate, TaskUpdate, TaskList, mcp__plugin_power-pages_playwright__browser_navigate, mcp__plugin_power-pages_playwright__browser_snapshot, mcp__plugin_power-pages_playwright__browser_click

plugins/power-pages/skills/create-webroles/SKILL.md

@@ -1,10 +1,9 @@
 ---
 name: create-webroles
-description: >
-  This skill should be used when the user asks to "create web roles", "add web roles",
-  "set up web roles", "add roles", "create roles for my site", "manage web roles",
-  "add authenticated role", "add anonymous role", or wants to create web roles for
-  their Power Pages code site. Web roles control access and permissions for site users.
+description: >-
+  Creates and configures web roles for a Power Pages code site. Web roles control access
+  and permissions for site users, including authenticated and anonymous roles. Use when the
+  user wants to create, add, set up, or manage web roles for their site.
 user-invocable: true
 allowed-tools: Read, Write, Bash, Grep, Glob, AskUserQuestion, Task, TaskCreate, TaskUpdate, TaskList
 model: opus

plugins/power-pages/skills/deploy-site/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: deploy-site
-description: This skill should be used when the user asks to "deploy to power pages", "upload site", "publish site", "deploy site", "push to power pages", "upload code site", or wants to deploy/upload an existing Power Pages code site to a Power Pages environment using PAC CLI.
+description: >-
+  Deploys an existing Power Pages code site to a Power Pages environment using PAC CLI.
+  Handles tooling verification, authentication, environment confirmation, building, and
+  uploading. Use when the user wants to deploy, upload, or publish their code site.
 user-invocable: true
 allowed-tools: Read, Bash, AskUserQuestion, Glob, Grep, TaskCreate, TaskUpdate, TaskList
 model: sonnet