Using Plugins

Out of the box, Claude is a generalist. It can write, research, and analyze — but it doesn’t know your standards, your workflows, or your preferred formats. Every time you start a new conversation, you’d need to re-explain how you want things done.

Plugins solve this. A plugin packages domain expertise — methodology, naming conventions, documentation templates, spec-writing patterns — into a format Claude can use automatically. Install a plugin once and Claude gains that expertise across every session.

The result: Instead of writing long prompts to explain what you want, you describe your goal in plain language and Claude applies the right expertise automatically.

Setting up Business-First AI Framework skills?

Start at the Set Up the Skills page for step-by-step setup instructions for your specific platform — Claude Chat, Cowork, Code, ChatGPT, Gemini, and M365 Copilot. This page covers advanced plugin management for the Claude ecosystem.

Looking for non-Claude platforms?

This page covers the Claude ecosystem (Claude Code, Claude.ai, Cowork, API). For Cursor, Codex CLI, Gemini CLI, VS Code Copilot, or any LLM, see How to Add Skills to Your Platform.

What’s Inside a Plugin

The plugin format supports agents, skills, commands, hooks, and MCP server connections. The Hands-on AI plugin currently provides:

• Agents — Expert personalities that Claude activates automatically based on your request. The framework-orchestrator agent walks you through the full Business-First AI Framework.
• Skills — Step-by-step workflows (an instruction file plus optional reference material) that teach Claude specific tasks. A skill might encode a methodology step, a documentation template, or a spec-writing pattern.
• Commands — Slash commands that trigger specific actions (like /handsonai:analyze for the Analyze step).
• Hooks — Automations that run in response to events (e.g., running a linter after every file edit).
• MCP servers — Connections to external tools and services (e.g., Notion, GitHub, Slack).

The Hands-on AI plugin currently focuses on agents and skills. As it grows, it may also include hooks and connectors.

Agents vs Skills

	Agents	Skills
What they are	Expert personalities (orchestrator, methodology guide)	Step-by-step workflows with instructions + reference material
How they activate	Claude automatically picks the right one based on your request	Automatically when relevant, or type /handsonai:skill-name
Where they work	Claude Code and Cowork	Claude Code, Claude.ai (upload as ZIP), and Cowork
Example	”Walk me through the Business-First AI Framework” activates framework-orchestrator	”Name this workflow” loads naming-workflows conventions

Transparency & Security

The plugin is plain-text Markdown — there’s no compiled code or hidden logic. Every agent and skill is fully readable, so you can review exactly what instructions Claude receives before you install anything.

Review the source: All plugin files are open source in the handsonai-plugins GitHub repository. The plugin detail page lists every agent and skill with descriptions of what they do.

Anthropic’s guidance on third-party plugins

Anthropic recommends reviewing any plugin before installing it. From the official plugin documentation: “Make sure you trust a plugin before installing it. Anthropic does not control what MCP servers, files, or other software are included in plugins and cannot verify that they work as intended.”

The Hands-on AI plugin contains only Markdown instruction files — no MCP servers, no executable code, and no external network calls. You can verify this yourself by browsing the plugin source.

Getting Started in Claude Code

Prerequisites

• Claude Code installed and working (Getting Started with Claude)
• An active Claude Pro, Max, Team, or Enterprise subscription (plugins are not available on the free plan)

Step 1: Add the Marketplace

A marketplace is a collection of plugins hosted online. Adding it tells Claude Code where to find plugins you can install. You only need to add it once.

In your Claude Code session, type:

/plugin marketplace add jamesgray-ai/handsonai-plugins

This tells Claude Code where to find the Hands-on AI plugin. It does not install anything yet. For more on how marketplaces work, see the official Discover and install plugins guide.

Tip

You can see which marketplaces you’ve added with /plugin marketplace list.

Step 2: Install the Plugin

To install the Hands-on AI plugin, type:

/plugin install handsonai@handsonai

After installing, the plugin’s agent and skills are available in your Claude Code session. Installed plugins are stored in ~/.claude/plugins/ on your machine.

Step 3: Use It

Installed plugins add an agent and skills that Claude Code can use automatically. You don’t need to call them by name — just describe what you need and Claude will use the right one.

Agent — just talk naturally

Describe what you need. Claude Code matches your request to the agent automatically.

Examples:

"Walk me through the Business-First AI Framework for this workflow"
→ framework-orchestrator activates

"Help me apply AI to my client onboarding process"
→ framework-orchestrator activates and starts at Analyze

Claude Code shows which agent it selected at the top of the response. You can list all available agents with /agents.

Skills — natural language or slash commands

Skills activate the same way — describe what you need and the relevant skill loads automatically.

You can also invoke a skill directly with a slash command. The format is /handsonai:command:

Slash command	What it does
/handsonai:analyze	Audit your workflows to find AI opportunities
/handsonai:deconstruct	Break a workflow into structured steps
/handsonai:design	Design the AI workflow architecture
/handsonai:build	Generate platform-appropriate artifacts
/handsonai:test	Test artifacts and evaluate output quality
/handsonai:run	Generate a Run Guide for deployment
/handsonai:improve	Evaluate a running workflow
/handsonai:naming-workflows	Generate consistent workflow names + Notion entry
/handsonai:writing-workflow-sops	Write a Standard Operating Procedure
/handsonai:writing-process-guides	Write a Business Process Guide
/handsonai:registering-building-blocks	Register a building block in Notion
/handsonai:writing-vision-briefs	Capture a fuzzy idea as a Vision Brief
/handsonai:writing-feature-prds	Write a feature PRD with user stories and acceptance criteria

The plugin detail page describes each one in depth, with example prompts and expected outputs.

Note

The AI Registry skills work best with the Notion MCP connector configured. Without it, Claude can follow the naming conventions and draft the output but cannot read from or write to Notion.

Checking what’s installed

/plugin list

This shows all installed plugins with their agents and skills. For the full plugin management commands (scopes, updates, disabling), see the official Discover and install plugins documentation.

Using Skills in Claude.ai (Web)

Claude.ai supports skills through a ZIP upload process. You can take any plugin skill and use it on the web — no terminal required.

Prerequisites

• Claude Pro, Max, Team, or Enterprise plan
• Code execution enabled in Settings > Capabilities (this lets Claude run skills — it does not give Claude access to your computer)

Upload a plugin skill to Claude.ai

1. Get the skill ZIP

The fastest path is to download the pre-built ZIPs from GitHub Releases. Every skill in the plugin is published as an individual .zip file with each release.

If you’ve installed the plugin in Claude Code, you can also zip the skill folder yourself from your local plugin directory at:

~/.claude/plugins/marketplaces/handsonai/plugins/handsonai/skills/<skill-name>/

Terminal command (optional — faster)

If you’re comfortable with Terminal, this is faster. Otherwise, use the Finder method. Open Terminal and paste this command, replacing <skill-name> with the actual name:

cd ~/.claude/plugins/marketplaces/handsonai/plugins/handsonai/skills && \
  zip -r ~/Desktop/<skill-name>.zip <skill-name>/

Concrete example for analyze:

cd ~/.claude/plugins/marketplaces/handsonai/plugins/handsonai/skills && \
  zip -r ~/Desktop/analyze.zip analyze/

The ZIP file appears on your Desktop.

Finder (visual)

1. Open Finder
2. From the menu bar, click Go → Go to Folder… (or press Cmd + Shift + G)
3. Paste this path and press Enter:

   ~/.claude/plugins/marketplaces/handsonai/plugins/handsonai/skills/

4. Right-click the skill folder (e.g., analyze) and choose Compress

Common mistake

Zip the folder itself, not the individual files inside it. When you open the ZIP, you should see a single folder (e.g., analyze/) — not loose files.

2. Upload to Claude.ai

Go to Settings > Capabilities > Upload skill. Select your .zip file.

3. Toggle the skill on

Find your uploaded skill in the Skills list and enable it.

4. Start using it

Open a new chat and describe your need. Claude automatically uses the skill when relevant.

Walkthrough: analyze in Claude.ai

The analyze skill is the entry point to the Business-First AI Framework — find AI opportunities in your work.

• Path: ~/.claude/plugins/marketplaces/handsonai/plugins/handsonai/skills/analyze/
• Contents: SKILL.md and reference files
• Terminal zip command:

  cd ~/.claude/plugins/marketplaces/handsonai/plugins/handsonai/skills && \
    zip -r ~/Desktop/analyze.zip analyze/

• Test prompt in Claude.ai: “Help me find where AI could create the most value in my work”

Claude applies the framework methodology from the skill’s reference file automatically.

What about agents in Claude.ai?

In Claude Code, Claude automatically picks the right agent for your request. This automatic selection does not exist in Claude.ai.

Agent files have a different format from skill files and cannot be uploaded as skills directly. For agent-like behavior in Claude.ai, you can:

• Create a Project and paste the agent’s instructions as custom instructions
• Convert the agent into a skill (wrap its instructions in a SKILL.md file)

Skill compatibility across platforms

All 13 skills work fully across Claude Code, Claude.ai, and Cowork.

Skill	Claude Code	Claude.ai	Cowork	Notes
analyze	Full	Full	Full	Pure instructions + reference docs
deconstruct	Full	Full	Full	Pure instructions + reference docs
design	Full	Full	Full	Pure instructions + reference docs
build	Full	Full	Full	Pure instructions + reference docs
test	Full	Full	Full	Pure instructions + reference docs
run	Full	Full	Full	Pure instructions + reference docs
improve	Full	Full	Full	Pure instructions + reference docs
naming-workflows	Full	Full	Full	Notion MCP recommended for save-to-Notion
writing-workflow-sops	Full	Full	Full	Notion MCP optional
writing-process-guides	Full	Full	Full	Notion MCP optional
registering-building-blocks	Full	Full	Full	Notion MCP required
writing-vision-briefs	Full	Full	Full	Pure instructions
writing-feature-prds	Full	Full	Full	GitHub CLI recommended for issue creation

Using Plugins in Claude Cowork

Cowork is a visual workspace inside the Claude Desktop app (macOS) designed for non-technical work — writing, research, analysis, and project coordination. You set the goal and Claude delivers finished, professional work. It’s available on Claude Pro, Max, Team, and Enterprise plans.

Cowork has its own built-in plugin directory, so you don’t need Claude Code or a terminal to use plugins. The directory includes plugins across productivity, marketing, legal, finance, data analysis, and more — browse the full catalog at claude.com/plugins-for/cowork.

Install a plugin in Cowork

1. Open Claude Desktop and click Cowork in the sidebar
2. Click the + button at the bottom of the screen (next to “Work in a folder”)
3. Select Add plugins… from the menu
4. Browse the plugin directory or upload a custom plugin file

You can also click the Customize with plugins card on the Cowork home screen to go directly to plugin setup.

What Cowork offers with plugins

• Plugins bundle skills, connectors, slash commands, and sub-agents
• Cowork coordinates parallel workstreams and delivers professional outputs (Excel, PowerPoint, formatted docs)
• Pairs with Claude in Chrome for browser-based tasks
• Pairs with MCP connectors for external tool access (e.g., Notion)
• Plugins are saved locally to your machine

Cowork vs Claude Code

	Cowork	Claude Code
Interface	Visual — no terminal needed	Terminal-based
Plugin discovery	+ button > Add plugins… or plugin directory	/plugin install command
Agent activation	Via plugin commands	Auto-routing based on request
Best for	Knowledge workers, non-technical users	Developers, coding tasks
Plugin format	Same plugin files	Same plugin files

Both support the same plugin format and skill files. If you’re not comfortable with the terminal, Cowork is the recommended path.

Download from GitHub

Every file is plain-text Markdown — no compiled code, no special format. You don’t need Claude Code or plugins to use them. Download skill folders from GitHub and place them in your platform’s skill directory. See How to Add Skills to Your Platform for step-by-step instructions for Claude Code, Cursor, Codex CLI, Gemini CLI, and VS Code Copilot.

GitHub: Browse the plugin on GitHub

GitHub Releases: Download individual skill ZIPs

Other ways to use them:

• Upload to Claude.ai — zip a skill folder and upload it under Settings > Capabilities > Upload skill (detailed instructions)
• Use via the Claude API — embed skill content in the system parameter (code example)

Using Skills via the Claude API

For developers

Skills can be used programmatically through the Claude API in two ways.

Skills API

Upload custom skills via the /v1/skills endpoints, then reference them by skill_id in conversations:

import anthropic

client = anthropic.Anthropic()

# Reference an uploaded skill by ID
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=4096,
    skill_ids=["sk_analyze"],
    messages=[
        {"role": "user", "content": "Help me find AI opportunities in my workflow."}
    ]
)

System prompt approach

Alternatively, embed the content of SKILL.md (and any reference files) directly in the system parameter:

import anthropic

client = anthropic.Anthropic()

# Read SKILL.md content
with open("analyze/SKILL.md") as f:
    skill_content = f.read()

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=4096,
    system=skill_content,
    messages=[
        {"role": "user", "content": "Help me find AI opportunities in my workflow."}
    ]
)

Note

MCP-dependent skills (like registering-building-blocks) won’t work via the raw API since they require tool integrations that the API alone doesn’t provide.

Managing Plugins

Updating plugins

When the plugin is updated with new agents, skills, or improvements, pull the latest version:

/plugin update handsonai@handsonai

Or update all installed plugins at once:

/plugin update --all

Enabling auto-updates

By default, Claude Code only auto-updates official Anthropic marketplaces. Third-party marketplaces like Hands-on AI have auto-updates disabled, so you won’t receive new agents, skills, or fixes automatically.

To enable auto-updates for the Hands-on AI marketplace:

1. Run /plugin to open the plugin manager
2. Select the Marketplaces tab
3. Choose handsonai from the list
4. Select Enable auto-update

Once enabled, Claude Code refreshes the marketplace and updates installed plugins each time it starts. If any plugins were updated, you’ll see a notification suggesting you restart Claude Code.

Tip

You can still update manually at any time with /plugin update --all — auto-update just makes it happen automatically at startup.

For more details on auto-update behavior and environment variables, see the official Configure auto-updates documentation.

Uninstalling

To remove the plugin:

/plugin uninstall handsonai@handsonai

To remove the marketplace entirely:

/plugin marketplace remove handsonai

Migrating from the old plugins

If you previously installed business-first-ai, ai-workflow-examples, ai-registry, or agentic-coding, here’s the one-time migration:

/plugin uninstall business-first-ai@handsonai
/plugin uninstall ai-workflow-examples@handsonai
/plugin uninstall ai-registry@handsonai
/plugin uninstall agentic-coding@handsonai
/plugin install handsonai@handsonai

The skills you used (analyze, name-workflow, feature-prd, etc.) are all still here — only the plugin name and namespace changed. Slash commands move from /business-first-ai:analyze to /handsonai:analyze, etc.

The example agents and skills that aren’t in the new plugin (HBR-style writing, vendor-specific researchers, LinkedIn prospecting) live on as study material in the Example Gallery — copy and customize them if you used them.

Cowork users: Plugin updates require a remove-and-re-add (Cowork caches plugin versions), so the migration commands above apply equally to Cowork.

Platform Summary

Capability	Claude Code	Claude.ai	Cowork	API
Plugin install	/plugin install	Upload skills as ZIP	+ button > Add plugins…	Skills API
Agent auto-routing	Yes	No	No	No
Skills (auto-trigger)	Yes	Yes (after upload)	Yes (via plugin)	Yes (Skills API)
Skills (slash command)	/handsonai:command	No	/ commands	No
MCP / Connectors	Yes	Some skills (via MCP)	Yes (connectors)	No
Browser automation	No	No	Yes (Chrome)	No
Reference file loading	Automatic	Included in ZIP	Automatic (via plugin)	Manual
Best for	Developers	Quick skill use, any device	Knowledge work, non-technical users	Programmatic access

Troubleshooting

”Marketplace not found”

Make sure you’ve added the marketplace first:

/plugin marketplace add jamesgray-ai/handsonai-plugins

“Plugin not found”

Check the plugin name is spelled correctly and includes the @handsonai suffix:

# Correct
/plugin install handsonai@handsonai

# Wrong — missing marketplace suffix
/plugin install handsonai

“Permission denied” or authentication errors

The marketplace is public. If you see authentication errors, check your GitHub CLI configuration (GitHub Setup guide).

Run this in your terminal (not inside Claude Code):

gh auth status

“I installed the plugin but nothing happens”

Restart your Claude Code session. Then verify the plugin is installed:

/plugin list

If the plugin appears but the agent doesn’t activate, try being more explicit in your prompt — for example, “Walk me through the Business-First AI Framework for my client onboarding process” rather than just “help me with onboarding."

"Skill not working in Claude.ai”

1. Check that code execution is enabled in Settings > Capabilities
2. Check the compatibility table — some skills work best with Notion MCP
3. Make sure the skill is toggled on in your Skills list

”ZIP upload failed”

• The ZIP must contain a folder with SKILL.md inside it — not loose files at the root
• The name field in SKILL.md frontmatter must use only lowercase letters, numbers, and hyphens
• The ZIP file should not exceed the upload size limit

”Can’t find skill files”

If you’ve added the marketplace, skill files are on your machine at:

~/.claude/plugins/marketplaces/handsonai/plugins/handsonai/skills/<skill-name>/

You can also browse skill source files on GitHub at:

https://github.com/jamesgray-ai/handsonai-plugins/tree/main/plugins/handsonai/skills/<skill-name>/

Next Steps

• The Hands-on AI Plugin — see what’s included with example prompts for each agent and skill
• Notion Registry setup — required for AI Registry skills that save to Notion
• Example Gallery — copy and customize example agents, skills, and prompts