personal-assistant

A skill-first repository for reusable agent workflows, packaged for multiple agent runtimes and installable from Codex via npx skills.

What is This?

This repository serves as a marketplace for reusable agent workflows across agent runtimes. Claude Code packaging is still supported, but the canonical workflows live in plugins/*/skills/*.

Available Plugins

See individual plugin READMEs for detailed setup instructions.

Available Skills

Skills are model-invoked capabilities that agent runtimes can activate when triggered by natural language. They are organized by plugin:

common-engineering Skills

thinking-tools Skills

softskills Skills

Quick Start

1. Add Marketplace

/plugin marketplace add https://github.com/irfansofyana/ai-marketplace

2. Configure Environment Variables

Add to ~/.zshrc (macOS) or ~/.bashrc (Linux):

export TAVILY_API_KEY="your-tavily-api-key"     # https://tavily.com
export EXA_API_KEY="your-exa-api-key"           # https://exa.ai
export N8N_API_TOKEN="your-n8n-token"           # https://n8n.io (for p-assist)

Reload: source ~/.zshrc or source ~/.bashrc

3. Install Plugins (in dependency order)

/plugin install shared-mcp@ai-marketplace     # REQUIRED - install first
/plugin install p-assist@ai-marketplace       # Optional
/plugin install common-engineering@ai-marketplace  # Optional
/plugin install sys-maint@ai-marketplace      # Optional (macOS only)
/plugin install thinking-tools@ai-marketplace # Optional
/plugin install softskills@ai-marketplace     # Optional

Manual Installation (Alternative)

For local development or offline access:

git clone https://github.com/irfansofyana/ai-marketplace.git
cd ai-marketplace
/plugin marketplace add $(pwd)

Codex and Skills

This repo's existing plugins/*/skills/* structure is already discoverable by npx skills add. No extra wrapper layer is required for Codex.

For MCP servers, Codex does not use the Claude plugin marketplace flow. Instead, Codex reads MCP config from ~/.codex/config.toml globally or .codex/config.toml per trusted project.

Use in Codex via GitHub

If you use Codex inside ChatGPT, connect GitHub in ChatGPT Settings and authorize this repository. After that, Codex can read the repo directly from GitHub for analysis and coding tasks.

Install for local Codex usage

Tested commands:

# Inspect available skills from the repo
npx skills add irfansofyana/ai-marketplace --list

# Install one public skill by name into the current project (default scope)
npx skills add irfansofyana/ai-marketplace --skill mermaid

# Install globally for your user environment
npx skills add irfansofyana/ai-marketplace --global --skill mermaid

# Install for Codex only without prompts
npx skills add irfansofyana/ai-marketplace --agent codex --skill mermaid --yes

Use exact skill names with --skill. Plugin names such as common-engineering are not valid selectors. By default, npx skills add installs at project scope. Add --global (-g) when you want the skill available across projects in your user environment. Use --agent codex to target Codex specifically, and --yes (-y) to skip interactive prompts.

Install shared-mcp for Codex

The shared-mcp bundle is now installable for Codex through a repo-managed config template and installer script.

Global install across Codex:

bash codex/shared-mcp/install.sh --global

Project-scoped install for the current repo:

bash codex/shared-mcp/install.sh --project

This writes a managed block into Codex config.toml with these MCP server names:

• •shared_mcp_tavily
• •shared_mcp_exa
• •shared_mcp_brave_search

Those names are intentionally namespaced for Codex so the installer does not overwrite unrelated tavily, exa, or brave-search entries you may already have. The config forwards TAVILY_API_KEY, EXA_API_KEY, and BRAVE_API_KEY from your shell at runtime instead of storing the key values in the repo. OpenAI’s Codex MCP docs confirm that Codex MCP servers are configured either via codex mcp or config.toml, and that CLI plus IDE share the same config: https://developers.openai.com/codex/mcp

Per-skill path installs should target:

plugins/<plugin>/skills/<skill>

Important note: a whole-repo install or discovery will also surface personal/private skills such as analyze-cc-statements from p-assist. Treat p-assist as personal/private and do not market it as part of the public Codex-ready path.

Using with Other AI Agents (via OPKG)

This marketplace works with OpenPackage (OPKG) for 30+ AI platforms (Cursor, Windsurf, Cline, OpenCode, etc.).

OPKG maps the universal structure to your platform's format:

Plugin Management

/plugin                                    # Browse and install plugins
/plugin enable|disable <plugin>@marketplace
/plugin uninstall <plugin>@marketplace
/help                                      # View all commands

Creating a Plugin

plugins/my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required: name, description, version, author
├── commands/                 # Optional: slash commands (.md files)
├── agents/                   # Optional: subagent definitions
├── skills/                   # Optional: SKILL.md files
├── hooks/                    # Optional: hooks.json
└── .mcp.json                # Optional: MCP server config

1. Create `plugin.json`:

{
  "name": "my-plugin",
  "description": "What it does",
  "version": "1.0.0",
  "author": { "name": "irfansofyana" }
}

2. Register in `.claude-plugin/marketplace.json`:

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin",
  "description": "Brief description"
}

3. Test:

/plugin uninstall my-plugin@ai-marketplace
/plugin install my-plugin@ai-marketplace

Troubleshooting

Learn More

• •Claude Code Docs
• •OPKG Docs

Author: irfansofyana