Upwork Agent Plugin

Portable agent workflows for hiring and finding work on Upwork. Learn more on the Upwork MCP site.

This repository follows the Agent Plugins specification v1.0.0. Compatible clients discover the remote MCP server from mcp.json and Agent Skills from immediate subdirectories of skills/.

Included components

• mcp.json connects to Upwork over the Streamable HTTP transport.
• skills/write-job-post guides clients from a rough need to a reviewed job post, then through publishing, updating, and closing it.
• skills/hire-on-upwork guides clients from candidates to a contract through freelancer search, proposal review, invitations, and offers.
• skills/write-proposal creates tailored, evidence-based proposals and guides freelancers through Connects, attachments, boosting, and submission review.
• skills/upwork-workflows defines the cross-cutting conventions: account selection, tool discovery, role routing, identifier handling, draft-confirm chains, pagination, and error handling.

Install

npx skills — recommended for any Agent Skills host

Install the skills in this repository with the open-source Skills CLI. It supports Claude Code, Cursor, Codex, and many other Agent Skills hosts:

npx skills add https://github.com/upwork/upwork-agent-plugin

The installer finds all four skills and prompts for which ones to install, which agents to configure, and whether to use project or global scope.

Claude Code

/plugin marketplace add upwork/upwork-agent-plugin

/plugin install upwork-agent-plugin@upwork

The plugin installation includes the skills and the Upwork MCP server declaration. Complete the browser-based authorization flow when prompted.

Codex

codex plugin marketplace add upwork/upwork-agent-plugin

codex plugin add upwork-agent-plugin@upwork

Alternatively, run codex, open /plugins, select Upwork, and install upwork-agent-plugin interactively.

Other Agent Plugin-compatible clients

Add this repository URL in the client's plugin installer:

https://github.com/upwork/upwork-agent-plugin

Compatible clients discover plugin.json, mcp.json, and every skill under skills/.

The root files are the portable Agent Plugins package. The .claude-plugin and .agents directories provide client-specific marketplace compatibility.

The Skills CLI installs the Agent Skills from this repository. On hosts that do not yet support the complete Agent Plugins format, MCP connector setup remains a separate client step.

After installation, ask the agent to connect to Upwork and describe the task, for example:

• "Help me turn this project brief into an Upwork job post."
• "Write a proposal for this Upwork job using my real work history."
• "Show my active Upwork contracts and any milestones needing attention."

The agent must request confirmation before write operations. Draft-based workflows require a second confirmation before the final marketplace action.

Structure

.
├── .agents/plugins/marketplace.json
├── .claude-plugin/
│   ├── marketplace.json
│   └── plugin.json
├── plugin.json
├── mcp.json
└── skills/
    ├── hire-on-upwork/
    │   └── SKILL.md
    ├── upwork-workflows/
    │   └── SKILL.md
    ├── write-job-post/
    │   └── SKILL.md
    └── write-proposal/
        └── SKILL.md

Validate

Validate the manifests against the canonical schemas:

curl -fsS https://agent-plugins.org/schemas/1.0.0/plugin.schema.json \
  -o /tmp/agent-plugin.schema.json
curl -fsS https://agent-plugins.org/schemas/1.0.0/mcp.schema.json \
  -o /tmp/agent-plugin-mcp.schema.json

npx --yes ajv-cli@5.0.0 validate --spec=draft2020 \
  -s /tmp/agent-plugin.schema.json \
  -d plugin.json

npx --yes ajv-cli@5.0.0 validate --spec=draft2020 \
  -s /tmp/agent-plugin-mcp.schema.json \
  -d mcp.json

Validate each skill with the Agent Skills reference validator:

python3 -m pip install skills-ref==0.1.1

for skill in skills/*/; do
  agentskills validate "$(pwd)/${skill%/}"
done

Contributing

Keep portable components in the standard fixed locations:

• plugin.json at the repository root
• mcp.json at the repository root
• skills/<skill-name>/SKILL.md, one level below skills/

Do not add secrets, access tokens, or fixed authorization headers to mcp.json.