Skills

Platforms: claude openai (via Codex CLI) · gemini (via Gemini CLI) · m365-copilot (via VS Code Copilot)

What Skills Are

Skills are folders containing instructions, scripts, and resources that the AI discovers and loads dynamically when relevant to a task. They encapsulate a specific capability — instructions, context, and output format bundled together — so you don’t have to re-explain the same task every time.

Skills are now an open standard and being adopted broadly across platforms. Think of them as upgraded prompts: they package a prompt with its context into something reusable, shareable, and automatically invocable.

Key Characteristics

• Encapsulates a specific capability — instructions, context, and output format bundled together
• Dynamically loaded or directly invoked — the AI discovers and loads skills automatically when relevant, or you invoke them with a slash command (/plugin-name:command)
• Reusable across conversations — write once, use every time the task comes up
• Shareable — skills can be distributed to others through plugins or file sharing
• Becoming an open standard — the skill format is being adopted across compatible platforms

When to Use a Skill

Use a skill when:

• You find yourself writing the same prompt repeatedly
• A workflow step is well-defined enough to package as a repeatable routine
• Consistency matters — the output should follow the same structure every time
• You want others to be able to run the same task with the same quality

A good rule of thumb: if you give an AI the same instructions more than three times, it’s time to package those instructions as a skill.

Skills vs. Agents

A skill is a routine — it does one thing well when invoked. An agent is autonomous — it decides what to do, which tools to use, and when to invoke skills. Think of skills as tools in a toolbox and agents as the person using the toolbox.

Platform Implementations

Agent Skills are an open standard — the same SKILL.md format works across platforms. Each platform reads skill files from its own directory, but the file format is identical:

Platform	Skill Directory	Notes
Cowork	Managed by plugin system	Install via + > Add plugins — no file placement needed
Claude Code	.claude/skills/	Also installable via plugins (/plugin install)
Claude.ai (web)	Uploaded via Settings	ZIP upload under Settings > Capabilities > Upload skill
Cursor	.cursor/skills/, .claude/skills/, .codex/skills/, or .agents/skills/	Reads from Claude and Codex directories too — no need to move files
Codex CLI	.agents/skills/	Same SKILL.md format
Gemini CLI	.gemini/skills/ or .agents/skills/	Same SKILL.md format
VS Code Copilot	.github/skills/ or .agents/skills/	Same SKILL.md format

Cross-platform convention

.agents/skills/ is a shared convention recognized by Cursor, Codex CLI, Gemini CLI, and VS Code Copilot. Place your skills there to make them available across multiple platforms from one location.

Anatomy of a Skill

A skill is a folder containing:

skill-name/
├── SKILL.md          # Instructions — what the skill does and how
└── references/       # Optional context files the skill needs
    ├── style-guide.md
    └── template.md

The SKILL.md file contains the instructions. The references/ folder holds any context the skill needs — style guides, templates, examples, or data.

On Claude Code, skills with user_invocable: true and a command: field in their frontmatter can be invoked directly as slash commands.

How to Add Skills to Your Platform

Setting up Business First AI Framework skills?

Go to Set Up the Skills for step-by-step setup instructions for your specific platform.

Without a skill, you write a detailed prompt every time you want consistent output. With a skill installed, you just say “edit this article” and the AI applies your editorial standards automatically — same quality, every time, no re-explaining.

Skills are plain-text Markdown — no compiled code, no special format. A plugin is a bundle that may contain multiple skills. On platforms that support plugins (Cowork, Claude Code), you install the whole plugin. On other platforms, you download and place individual skill folders.

Pick your platform below for the complete install steps.

No skill directory? No problem

Some platforms — like the Gemini app, M365 Copilot, and Perplexity — don’t have a skill directory. You can still use skills by pasting the SKILL.md contents into your platform’s equivalent feature (Gems, Notebooks, or Spaces). See the Other AI Tools tab below.

Install steps by platform

Cowork

The simplest path — no terminal needed.

1. Open Claude Desktop and click Cowork in the sidebar
2. Click the + button at the bottom of the screen
3. Select Add plugins… and browse or search for a plugin

Skills from the plugin are available immediately in Cowork.

→ Full Cowork plugin guide

Claude Code

One command installs everything.

/plugin install business-first-ai@handsonai

First time? Add the marketplace first (one-time setup):

/plugin marketplace add jamesgray-ai/handsonai-plugins

→ Full Claude Code plugin guide

Claude.ai (Web)

Upload skills as ZIP files — no terminal required.

1. Go to the GitHub plugins page. Click the green Code button > Download ZIP. Extract the ZIP, then navigate to plugins/<plugin-name>/skills/<skill-name>/ to find the skill folder you need.
2. Compress the skill folder into a .zip file (right-click > Compress in Finder)
3. Go to Settings > Capabilities > Upload skill and select the ZIP

→ Detailed ZIP upload walkthrough

Other Platforms

For Cursor, Codex CLI, Gemini CLI, and VS Code Copilot — download skill folders and place them in your project. Your project root is the top-level folder you opened in your editor or terminal.

1. Go to the GitHub plugins page. Click the green Code button > Download ZIP. Extract the ZIP, then navigate to plugins/<plugin-name>/skills/<skill-name>/ to find the skill folder you need.
2. Copy the skill folder into the directory for your platform:

Platform	Directory
Cursor	.cursor/skills/
Codex CLI	.agents/skills/
Gemini CLI	.gemini/skills/
VS Code Copilot	.github/skills/

Cross-platform shortcut

All four platforms also recognize .agents/skills/. Place skills there to share them across platforms from one location. Cursor additionally reads from .claude/skills/ and .codex/skills/, so skills installed for Claude Code are picked up automatically.

Other AI Tools

Skills are plain Markdown — platforms without a skill directory can still use them. Paste the SKILL.md contents into your platform’s equivalent feature and the AI will follow the skill’s interview structure and output format.

1. Go to the GitHub plugins page. Navigate to plugins/<plugin-name>/skills/<skill-name>/ and open the SKILL.md file. Copy its full contents.
2. Create a persistent instruction container on your platform:

Google Gemini (Gems)

1. Open Gemini and click New Gem
2. Name the Gem to match the skill (e.g., “Analyze Workflows”)
3. Paste the SKILL.md contents into the Gem’s instructions field
4. Save — select the Gem from the sidebar to use it in any conversation

M365 Copilot (Notebooks)

1. Open Microsoft Copilot and create a new Notebook
2. Click the expand button next to your notebook name and paste the SKILL.md contents as custom instructions
3. The instructions apply to all prompts within that Notebook

Perplexity (Spaces)

1. Open Perplexity and click Create a Space
2. Name the Space to match the skill
3. Tap Add Instructions and paste the SKILL.md contents
4. Instructions apply to all threads within that Space (requires Perplexity Pro)

What about file-saving instructions?

When a skill says it will save output to a file, the AI will present the output in the chat instead. Copy it yourself if you want to keep it.

Verify

Test that your platform picks up the skill by asking it to perform a task the skill handles:

• Cowork or Claude.ai: Start a new conversation and say “Edit this paragraph for HBR quality” — Claude should apply editorial criteria from the skill
• Claude Code: Type /business-first-ai:analyze to invoke the skill directly
• Cursor, Codex CLI, Gemini CLI, VS Code Copilot: Ask “Use the editing-hbr-articles skill to review this paragraph” — the AI should reference the skill’s instructions in its response
• Gemini, M365 Copilot, Perplexity: Open your Gem, Notebook, or Space and ask it to start the workflow — it should follow the skill’s structured interview process

Skill, Project, or Prompt?

Approach	Best For	Example
Prompt	One-off or infrequent tasks	”Summarize this PDF”
Project	Recurring context without rigid steps	Client research workspace
Skill	Repeatable process with consistent format and standards	Weekly status report generation

Guides

Guide	Description
Discover Your Best Claude Skills	Guided process to identify your highest-value skill candidates
The Complete Guide to Building Skills for Claude	Anthropic’s official guide covering skill structure, best practices, and advanced patterns
Improving skill-creator: Test, measure, and refine Agent Skills	How to test, measure, and iteratively refine skills using the skill-creator workflow

Related

• Agentic Building Blocks — Skills in the context of all building blocks
• AI Use Cases — what teams build with skills, organized by six primitives
• Prompts — the foundation that skills build on
• Agents — autonomous systems that invoke skills as part of multi-step workflows
• Agents & Skills — pre-built skills you can download or install