/$$      /$$ /$$$$$$$         /$$$$$$  /$$       /$$ /$$ /$$          
| $$$    /$$$| $$__  $$       /$$__  $$| $$      |__/| $$| $$          
| $$$$  /$$$$| $$  \ $$      | $$  \__/| $$   /$$ /$$| $$| $$  /$$$$$$$
| $$ $$/$$ $$| $$$$$$$/      |  $$$$$$ | $$  /$$/| $$| $$| $$ /$$_____/
| $$  $$$| $$| $$____/        \____  $$| $$$$$$/ | $$| $$| $$|  $$$$$$ 
| $$\  $ | $$| $$             /$$  \ $$| $$_  $$ | $$| $$| $$ \____  $$
| $$ \/  | $$| $$            |  $$$$$$/| $$ \  $$| $$| $$| $$ /$$$$$$$/
|__/     |__/|__/             \______/ |__/  \__/|__/|__/|__/|_______/ 

Reusable, local-first skill library for coding agents. Install once, use across Claude Code, Codex, Gemini CLI, Cursor, OpenCode, and any agent that reads SKILL.md files. Learn more.

What are skills?

A skill is a self-contained directory that teaches a coding agent how to perform a specific task. Each skill directory contains:

• SKILL.md — the primary instructions, workflow, and YAML frontmatter that the agent reads
• references/ — optional supporting docs loaded on demand (not all at once)
• scripts/ — optional helper automation

The SKILL.md frontmatter tells the agent what the skill does and when to use it. Here's a real example from the brainstorming skill:

---
name: brainstorming
description: "Facilitate structured technical brainstorming sessions. Use this skill to explore options, challenge assumptions, and produce implementation-ready plans for coding agents."
license: MIT
metadata:
   plan_mode: "true"
   author: Balazs Barta
   version: "2.2.0"
   tags:
      - brainstorming
      - facilitation
      - decision-making
      - planning
---

The description field is how agents decide when to activate a skill — it's matched against the user's request or current context. Reference files in references/ are loaded only when the skill's workflow calls for them, keeping context usage efficient.

Skills follow the open agentskills.io spec.

How agents use skills

Different agents discover and invoke skills in different ways:

| Agent | How to invoke | Auto-activation | Skill directory | | ----------- | ------------------------------------------------------------ | ------------------------------------------- | ------------------- | | Claude Code | Slash commands (/skill-name) or automatic context matching | Yes — matches description to current task | .claude/skills/ | | Codex | Automatic context matching or explicit invocation | Yes — matches description to current task | .codex/skills/ | | Gemini CLI | Native SKILL.md discovery, context-based | Yes — reads SKILL.md files automatically | .gemini/skills/ | | Cursor | Native SKILL.md discovery, context-based | Yes — reads SKILL.md files automatically | .cursor/skills/ | | OpenCode | Context-based discovery | Yes — matches description to current task | .opencode/skills/ |

plan_mode frontmatter: For validator compatibility, set plan mode as metadata.plan_mode: "true" (not as a top-level field). Agents that support a dedicated plan mode (like Claude Code) will enter it automatically.

Skill cross-references: Skills can reference other skills using relative paths (e.g., ../task-breakdown/SKILL.md). This lets one skill hand off to another — for example, brainstorming can hand off to task-breakdown for detailed implementation planning. Note: Cross-referencing skills require the full pack to be installed. If you install only a subset, relative-path links between skills will break silently.

Brainstorming artifacts (ai-docs)

The brainstorming skill persists its session output in ai-docs/ and uses a helper script to create deterministic folders/files.

Script

.agents/skills/brainstorming/scripts/init_ai_docs.sh "<topic-slug>"

This creates:

ai-docs/
  brainstorming/
    <YYYY-MM-DD>-<topic-slug>/findings.md
  task-breakdown/
    <YYYY-MM-DD>-<topic-slug>/tasks.md

Session closeout behavior

1. Complete brainstorming in plan mode.
2. Exit plan mode.
3. Run the script above.
4. Write finalized findings to findings.md.
5. Ask whether to use .agents/skills/task-breakdown/SKILL.md for task generation.

If .agents/skills/task-breakdown/SKILL.md is not installed, continue with a manual task list in tasks.md or install the skill first.

Available skills

Each skill's description determines when agents activate it. Browse the full list:

| Skill | Description | | ------------------------ | ---------------------------------------------------------------------------------------------- | | accessibility-standards | Accessibility standards guide for WCAG/WACG, a11y audits, remediation patterns, and testing. | | brainstorming | Facilitate structured technical brainstorming sessions and produce implementation-ready plans. | | conventional-commits | Conventional Commits guide for commit format, scopes, and automated release workflows. | | debugging | Structured debugging workflow using Diagnose-Propose-Confirm with evidence-based diagnosis. | | documentation | AI-assisted documentation drafting using Draft-Review-Refine anchored to source material. | | jest | Jest testing guide for config, mocking, snapshots, transforms, and common issues. | | maestro | Maestro mobile E2E testing guide for flows, assertions, and CI usage. | | mastra | Mastra framework guide for current API usage, docs lookup, and agent/workflow patterns. | | next-js | Next.js App Router guide for routes, caching, metadata, and common errors. | | playwright | Playwright E2E guide for page objects, fixtures, CI, and visual regression. | | pull-request-lifecycle | Deterministic pull request workflow with changelog/version handling. | | react-native-expo | React Native + Expo guide for navigation, native modules, and EAS workflows. | | supabase | Supabase guide for auth, RLS, migrations, Edge Functions, and storage. | | task-breakdown | Task decomposition and estimation guide for epics, stories, and implementation tasks. | | vitest | Vitest testing guide for config, mocking, component tests, and coverage. |

Install

This repo ships a skills CLI (scripts/skills.mjs) so you can install to different assistants with one command.

Quick install

For installation, run the following command:

npx @balazsbarta/mp-skills add mp-skills

Targets:

• codex
• claude-code
• opencode
• gemini-cli
• cursor
• generic (for other agents; defaults to .agents/skills/)
• all

Useful options:

• --mode copy|symlink (default: copy)
• --global — install to global home directories instead of project-local paths
• --cursor-project /path/to/project (used by cursor)
• --dest /path/to/skills (used by generic)

Install paths (default: project-local):

| Target | Local (default) | Global (--global) | | ------------- | ------------------------------------- | ---------------------------- | | codex | <cwd>/.codex/skills/ | ~/.codex/skills/ | | claude-code | <cwd>/.claude/skills/ | ~/.claude/skills/ | | opencode | <cwd>/.opencode/skills/ | ~/.config/opencode/skills/ | | gemini-cli | <cwd>/.gemini/skills/ | ~/.gemini/skills/ | | cursor | <cwd>/.cursor/skills/ | (always project-local) | | generic | <cwd>/.agents/skills/ (or --dest) | (uses --dest) |

Mode behavior:

• symlink applies to all folder-based targets (codex, claude-code, opencode, gemini-cli, cursor, generic)

Manual installs

Codex

Copy install:

SKILLS_HOME=".codex/skills"
mkdir -p "$SKILLS_HOME"
cp -R .agents/skills/* "$SKILLS_HOME/"

Symlink install:

SKILLS_HOME=".codex/skills"
mkdir -p "$SKILLS_HOME"

for dir in .agents/skills/*; do
  name="$(basename "$dir")"
  target="$SKILLS_HOME/$name"

  if [ -e "$target" ] || [ -L "$target" ]; then
    rm -rf "$target"
  fi

  ln -s "$(pwd)/$dir" "$target"
done

Claude Code

Skills are installed as folders in .claude/skills/<skill-name>/.

CLAUDE_SKILLS_DIR=".claude/skills"
mkdir -p "$CLAUDE_SKILLS_DIR"

for dir in .agents/skills/*; do
  name="$(basename "$dir")"
  ln -sfn "$(pwd)/$dir" "$CLAUDE_SKILLS_DIR/$name"
done

OpenCode

OpenCode skills are installed to .opencode/skills/ by default.

OPENCODE_SKILLS_DIR=".opencode/skills"
mkdir -p "$OPENCODE_SKILLS_DIR"

for dir in .agents/skills/*; do
  name="$(basename "$dir")"
  ln -sfn "$(pwd)/$dir" "$OPENCODE_SKILLS_DIR/$name"
done

Gemini CLI

Gemini CLI skills are installed to .gemini/skills/ by default. Gemini CLI discovers SKILL.md files natively.

GEMINI_SKILLS_DIR=".gemini/skills"
mkdir -p "$GEMINI_SKILLS_DIR"

for dir in .agents/skills/*; do
  name="$(basename "$dir")"
  ln -sfn "$(pwd)/$dir" "$GEMINI_SKILLS_DIR/$name"
done

Cursor / Cursor CLI

Cursor skills are installed to .cursor/skills/. Cursor discovers SKILL.md files natively.

CURSOR_SKILLS_DIR=".cursor/skills"
mkdir -p "$CURSOR_SKILLS_DIR"

for dir in .agents/skills/*; do
  name="$(basename "$dir")"
  ln -sfn "$(pwd)/$dir" "$CURSOR_SKILLS_DIR/$name"
done

Or use the installer for a different project directory:

npx @balazsbarta/mp-skills add mp-skills --target cursor --cursor-project /path/to/project

Other agents

Use the generic target to install skill folders to any custom location:

npx @balazsbarta/mp-skills add mp-skills --target generic --dest /path/to/agent/skills --mode symlink

Or use the default .agents/skills/ location:

npx @balazsbarta/mp-skills add mp-skills --target generic

Verify install

Codex:

ls -la .codex/skills

Claude Code:

ls -la .claude/skills

OpenCode:

ls -la .opencode/skills

Gemini CLI:

ls -la .gemini/skills

Cursor:

ls -la .cursor/skills