AI Agent Skills

pptb-agent-skills is a companion repository of instructions for AI coding assistants — Claude Code, Cowork, GitHub Copilot, and OpenAI Codex — to develop Power Platform ToolBox (PPTB) tools, review marketplace policy compliance, and assess Verified badge readiness. The skills are grounded in these docs, marketplace policies, and the generator-pptb scaffolding tool.

Overview

The repository contains three skills in the open SKILL.md format (YAML frontmatter and Markdown):

• pptb-tool-dev — the source folder is tool-dev. Scaffold, fix, debug, validate, and publish PPTB tools.
• intake-policy-review — review marketplace and AI-assisted-development policy compliance using current policies and repository evidence.
• tool-verification — assess every current Verified badge criterion, including evidence gaps, marketplace data, and decisions reserved for human reviewers.

The name used with the installer's --skill option is each skill's YAML frontmatter name. It can differ from its source folder: for example, install pptb-tool-dev, not tool-dev.

Claude Code, GitHub Copilot, and Codex read the same SKILL.md format. Once installed, describe the task naturally and the coding agent follows the matching skill's workflow. The skills provide instructions; they are not standalone review or development services.

What the Skills Teach

Tool development — pptb-tool-dev

The skill walks an agent through the tool lifecycle:

• Scaffolding with yo pptb / generator-pptb and selecting a framework
• Fixing package.json and pptb.config.json so they pass pptb-validate, following Package Manifest
• Wiring up inter-tool invocation (launchTool, getLaunchContext, returnData) as described in Inter-Tool Invocation
• Exposing a tool to AI assistants over MCP with the agents block and invokeHeadless entry point described in Agent Integration

Marketplace intake — intake-policy-review

This skill reviews a tool repository, tool subfolder, or local project against the current Marketplace Policy and AI-Assisted Development Policy. It inspects repository evidence rather than relying on the README alone.

The review covers:

• Marketplace metadata, naming, publisher attribution, icons, and whether README claims match the implementation
• Read/write behavior, including preview, confirmation, environment locking, and rollback safeguards for state-changing tools
• The required ## What this tool changes README section where applicable
• API usage, bounded operations, pagination, batching, and concurrency
• Privacy, external network calls, telemetry, and CSP behavior
• Screenshot authenticity, real-environment testing, AI assistance disclosure where applicable, dependency audits, validation, and theme testing

The report includes an overall assessment, an Area / Status / Finding table, detailed findings with concrete replacement snippets where useful, prioritized pre-submission changes, and a readiness verdict. It distinguishes policy requirements from recommendations and does not impose destructive-operation controls on read-only tools.

Verified badge readiness — tool-verification

This skill targets the Verified maturity review after marketplace intake. It accepts a repository, branch, tag, commit, or tool-subfolder URL; reads the live Tool Maturity Model on every review; and assesses every required and optional criterion plus submission prerequisites.

The criteria include:

• README quality, documented CSP exceptions, dependency vulnerabilities, supported PPTB APIs, host theme integration, and the packaged SVG icon
• Published version, bug response, active contributors, compatibility with breaking changes, and marketplace usage metrics
• Optional colour contrast and console-error checks

The report includes a criterion-by-criterion evidence table, prioritized fixes, missing evidence, and decisions reserved for human reviewers. It distinguishes Ready to request verification, Needs reviewer judgment, Not ready, and Incomplete assessment. Optional improvements do not block readiness, and missing evidence is not treated as a pass.

Every report ends with a Reviewer response list for the verification web form: one self-contained item per required and optional criterion, marked ✅, ❌, or ❔. High or critical vulnerabilities confined to build/development dependencies are marked Needs Manual Validation pending human review; confirmed runtime findings fail the check. The skill preserves reviewer discretion for soft gates and usage waivers. It cannot grant a Verified badge or reviewer waiver.

Prerequisites

• Node.js and npm — the skills CLI requires Node.js 22.20.0 or later. Use npm's npx command to run it; the CLI documentation does not specify a separate minimum npm version. Tool development also uses yo, generator-pptb, and @pptb/types (which provides pptb-validate); the skill does not install these automatically.
• PPTB desktop app if you want to exercise the development debug loop (dev-watch → Load Local Tool) described in Debugging Your Tool. It is not needed just to scaffold or validate.
• Claude Code / Cowork, GitHub Copilot, or OpenAI Codex with skills enabled so the assistant can load the installed SKILL.md.
• Policy and repository access for intake-policy-review. Node.js/npm supports local validation and dependency audits; the PPTB desktop app is needed for real-environment testing.
• Verification evidence access for tool-verification, including repository files, issue/comment history, releases, and current maturity/API docs. Marketplace usage, ratings, and ownership may require dated owner-provided evidence. Missing access must be reported as an evidence gap, not assumed to pass.

Installing the Skills

Recommended: install globally with npx skills

For a reusable setup across projects, install the skills globally for your user:

npx skills add PowerPlatformToolBox/pptb-agent-skills --global

Run the command from any directory. The CLI prompts you to choose skills and supported agents. Useful options include:

# List available skills without installing
npx skills add PowerPlatformToolBox/pptb-agent-skills --list

# Install one skill globally by its YAML frontmatter name
npx skills add PowerPlatformToolBox/pptb-agent-skills \
  --global --skill pptb-tool-dev

# Install all three skills globally
npx skills add PowerPlatformToolBox/pptb-agent-skills --global --skill '*'

To install globally for specific agent identifiers:

npx skills add PowerPlatformToolBox/pptb-agent-skills --global \
  --agent github-copilot --agent claude-code --agent codex

The CLI installs project-locally when --global is omitted. Use that scope when the skills should be specific to one project or committed for a team. The CLI recommends symlinks so a single installed copy can be shared; add --copy instead when you need copies rather than symlinks.

After installation, inspect and maintain installed skills with:

# List installed skills
npx skills list

# Check for available updates
npx skills check

# Update installed skills
npx skills update

See the upstream skills CLI command reference for additional options and the supported agents list for installation locations.

How installation is hosted

The skills CLI is maintained by Vercel Labs and npx obtains it from npm. The CLI retrieves the skill files from the PowerPlatformToolBox/pptb-agent-skills GitHub repository and installs them for your selected agent. This does not deploy a website or run a review: no Vercel account, Vercel website deployment, vercel.json, or custom npm package is required. The coding agent executes the installed workflow; the CLI only installs its instructions.

Alternative: copy the skill folders manually

Manual copying is available when you prefer not to use the CLI. Get the skills repository, then run the copy commands from its root. Copy the entire skill folder so any references/ files are included.

Claude Code / Cowork:

mkdir -p <project>/.claude/skills
cp -r tool-dev/ <project>/.claude/skills/pptb-tool-dev/
cp -r intake-policy-review/ <project>/.claude/skills/intake-policy-review/
cp -r tool-verification/ <project>/.claude/skills/tool-verification/

GitHub Copilot:

mkdir -p <repo>/.github/skills
cp -r tool-dev/ <repo>/.github/skills/pptb-tool-dev/
cp -r intake-policy-review/ <repo>/.github/skills/intake-policy-review/
cp -r tool-verification/ <repo>/.github/skills/tool-verification/

OpenAI Codex:

mkdir -p <repo>/.agents/skills
cp -r tool-dev/ <repo>/.agents/skills/pptb-tool-dev/
cp -r intake-policy-review/ <repo>/.agents/skills/intake-policy-review/
cp -r tool-verification/ <repo>/.agents/skills/tool-verification/

Before copying, check whether the destination already contains a skill with the same name. Avoid duplicate installations across project and global locations, and do not blindly overwrite an existing skill or local changes. Manually copied skills do not update through the CLI; copy updated files from the upstream repository yourself.

Review a GitHub repository without cloning it

The skills CLI downloads the skill instructions from pptb-agent-skills during installation. That is separate from cloning or downloading the target tool repository being reviewed. Install intake-policy-review and/or tool-verification globally, or into a separate review workspace, so the target project does not need to be checked out locally.

Give the coding agent the tool's GitHub URL. To inspect it remotely, the agent needs GitHub connector/MCP tools with access to the repository, plus web access to current policy and documentation pages. Private repositories require authorized GitHub access. A branch, tag, commit, or tool-subfolder URL can narrow the review scope.

If you prohibit cloning, explicitly tell the agent not to clone, download, or check out the target repository. It must respect that restriction, use GitHub tools to read files, and report inaccessible files or other evidence gaps rather than silently cloning. Remote source inspection is not equivalent to running a build, npm audit, pptb-validate, or live PPTB tests. CI evidence must correspond to the exact revision being reviewed. Missing execution or runtime evidence remains unverified, not a pass. Neither skill grants marketplace approval or a Verified badge.

Marketplace intake review prompt

Using the intake-policy-review skill, review this PPTB tool for marketplace
intake and AI-assisted-development policy compliance:
<GITHUB_URL>

Inspect the target repository remotely through GitHub connector/MCP tools.
Do not clone, download, or check out the target repository locally. You may
read its files, history, and metadata through GitHub tools. Check the current
Marketplace Policy and AI-Assisted Development Policy, plus relevant current
PPTB documentation. Report each finding with links to the supporting file,
line, commit, policy, or other evidence. Separate confirmed findings from
missing or inaccessible evidence; do not claim commands or runtime tests
passed unless there is revision-matched evidence that they ran.

Verified badge readiness prompt

Using the tool-verification skill, assess this PPTB tool against every current
Verified badge criterion and submission prerequisite:
<GITHUB_URL>

Inspect the target repository remotely through GitHub connector/MCP tools.
Do not clone, download, or check out the target repository locally. You may
read its files, history, releases, and metadata through GitHub tools. Read the
current Tool Maturity Model and relevant validation/API documentation.
Provide criterion-by-criterion statuses and evidence-linked findings; identify
missing marketplace or runtime evidence and every decision reserved for a
human reviewer. End with the complete Reviewer response list, one item for
each required and optional criterion. Do not treat inaccessible or unrun
checks as passes, and do not imply that this review grants a badge or waiver.

Using the Skills

Once installed, prompt the coding agent naturally; the description in each SKILL.md helps the agent select the relevant workflow.

Develop a PPTB tool with pptb-tool-dev

Install the development skill globally so it is available in the tool project and other projects:

npx skills add PowerPlatformToolBox/pptb-agent-skills \
  --global --skill pptb-tool-dev

Then ask the agent for the development task, for example:

Scaffold a PPTB tool that lets me bulk-update account records. Use the
official generator, inspect the project as you work, and validate the manifest.

For a fix, you could ask: "My tool's package.json keeps failing pptb-validate; inspect the project and fix it against the manifest schema." The skill guides the agent through scaffolding or changes, but development normally requires a working project and filesystem access. Live host testing requires the PPTB desktop app; remote repository inspection alone cannot complete every development task.

Other examples:

• "Make my tool launchable from another PPTB tool" → wire up launchTool / getLaunchContext / returnData without re-scaffolding.
• "Expose my tool to an agent via MCP" → add the agents block and an invokeHeadless entry point.
• "Review this PPTB repository for marketplace intake readiness" → use intake-policy-review to check current policies, repository evidence, findings, and prioritized pre-submission changes.
• "Check this tool folder against the marketplace and AI-assisted-development policies" → scope the review to that folder and check shared code when it affects the tool.
• "Check this GitHub repository against all PPTB verification requirements" → use tool-verification to assess every criterion, available evidence, gaps, and reviewer decisions.

Reference Files

The tool-dev/SKILL.md entry point defers to references/ files loaded on demand:

intake-policy-review has a standalone SKILL.md. It reads live policy pages and repository evidence during each review rather than relying on bundled policy snapshots.

tool-verification/SKILL.md uses two supporting files and reconciles their guidance with the live maturity model:

Scope and Limitations

• pptb-tool-dev scaffolds with generator-pptb (yo pptb); it does not use sample-tools, which maintainers consider outdated. Power-Maverick/PPTB-Tools is a pattern example, not a scaffolding template.
• intake-policy-review does not replace marketplace maintainer approval or real-environment human testing. It reports validation and audit commands as passed only when they were run or supported by repository evidence.
• tool-verification cannot grant a Verified badge or reviewer waiver. Private marketplace data and live PPTB behavior may need additional evidence; static inspection alone cannot prove host integration. The skill drafts reviewer responses without submitting the verification form or changing marketplace state.
• Remote inspection cannot run the target tool's build, npm audit, pptb-validate, or live PPTB tests. Existing CI evidence must match the reviewed revision. Unrun or inaccessible checks remain unverified, not passed.
• The CLI installs skill instructions only. The coding agent performs the development or review workflow, and the result depends on the agent's tools, permissions, and evidence access.

Next Steps