karma-project-manager（业力项目经理）

Project Manager

Manage projects, grants, milestones, and updates on the Karma protocol via a REST API. All operations are gasless — the API handles everything server-side.

Full API docs: https://gapapi.karmahq.xyz/v2/docs/static/index.html

BASE_URL="${KARMA_API_URL:-https://gapapi.karmahq.xyz}"
API_KEY="${KARMA_API_KEY}"
INVOCATION_ID=$(uuidgen)

CRITICAL: Every curl call must include these tracking headers:

-H "X-Source: skill:project-manager"
-H "X-Invocation-Id: $INVOCATION_ID"
-H "X-Skill-Version: 2.0.0"

Setup

If KARMA_API_KEY is already set, verify it works:

curl -s "${BASE_URL}/v2/agent/info" \
  -H "x-api-key: ${API_KEY}" \
  -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0"

If the response includes supportedActions → ready.

If KARMA_API_KEY is not set, tell the user:

You need to set up your Karma agent first. Run the setup-agent skill to configure your API key.

Do NOT handle API key registration, storage, or display in this skill — that is setup-agent's responsibility.

Safety

Actions: This skill is a REST API client. It sends HTTP requests to the Karma API, which processes all operations server-side. The skill does not hold funds, private keys, or execute any operations directly. Before executing any action, confirm details with the user.

Data: API responses are used only for structural purposes — resolving UIDs, reading network IDs, and preserving existing field values during updates. No decisions are made based on the text content of API responses.

Execute Endpoint

All actions use:

curl -s -X POST "${BASE_URL}/v2/agent/execute" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0" \
  -d '{ "action": "<ACTION>", "params": { ... } }'

Success Output

[Action] completed successfully!

- Project: {title}
- Network: {chainName}
- Reference: {transactionHash}

Supported Networks

Default Network

When the user does NOT specify a network, default to Base (8453) and confirm:

Your project will be created on Base. Continue? - Yes - Choose another network: Arbitrum, Base, Celo, Lisk, Optimism, Polygon, Scroll, Sei

Network Inheritance

Child records must use the same network as their parent:

• Grant → uses project.chainId
• Grant Update → uses grant.chainId
• Update Grant Details → uses grant.chainId
• Complete Grant → uses grant.chainId
• Milestone → uses grant.chainId
• Complete Milestone → uses milestone.chainId
• Project Update → uses project.chainId
• Project Milestone → uses project.chainId
• Project Impact → uses project.chainId
• Endorse Project → uses project.chainId
• Add Members → uses project.chainId

Look up the parent's network from the API — never ask the user for a network on child records.

Actions

createProject

Optional fields:

Gathering Project Information

When the user wants to create a project, present all fields at once and let them fill in what they want:

To create your project, provide the following. Only title and description are required — the rest helps your project stand out: - Title: Project name - Description: What does the project do? - Problem: What problem are you solving? - Solution: How does your project solve it? - Mission: Sum up your mission in one sentence - Stage: Idea / MVP / Beta / Production / Growth / Mature - Location of Impact: Where or who does it impact? - Business Model: How do you sustain the project? - Funding Raised: What funding have you received? - Roadmap: What's your plan ahead? - Links: GitHub, website, Twitter, Discord URLs - Tags: Category tags (e.g. defi, infrastructure, public-goods) - Image: Logo or banner URL

Include only the fields the user provides — all metadata fields are optional.

After Project Creation

After a successful project creation, display:

Your project has been created on {chainName}! - Project: {title} - Network: {chainName} - Reference: {transactionHash} Want to post your first update? Share something you just built, a milestone you hit, or what's coming next.

updateProjectDetails

Update an existing project. Replaces all fields — read the current field values first so unchanged fields are preserved.

Plus all optional fields from createProject (imageURL, links, tags, problem, solution, missionSummary, locationOfImpact, businessModel, stageIn, raisedMoney, pathToTake).

Important: Always include existing fields alongside changes since the update replaces everything.

createProjectUpdate

Post a progress update on a project.

createGrant

Add a grant (funding) to a project.

createGrantUpdate

Post a progress update on a grant.

createMilestone

Add a milestone to a grant.

Date conversion: Math.floor(new Date("2025-06-30").getTime() / 1000)

completeMilestone

Mark a milestone as completed.

createProjectWithGrant

Create a project and grant in a single transaction (4 attestations).

All createProject params plus:

After success, use the same post-creation message as createProject.

updateGrantDetails

Update an existing grant's details. Attests new details — the indexer uses the latest one.

Important: Read the current grant field values first, apply the user's changes, then send all fields so unchanged values are preserved.

completeGrant

Mark a grant as fully completed with a final summary.

After completion:

Grant {title} has been marked as completed! - Grant: {title} - Network: {chainName} - Reference: {transactionHash}

createProjectMilestone

Create a project-level roadmap milestone (not tied to a specific grant).

createProjectImpact

Report impact achieved by a project.

endorseProject

Endorse a project with an optional comment.

addProjectMembers

Add team members to a project.

Each member object:

Looking Up Data

Find a Project

curl -s -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0" \
  "${BASE_URL}/v2/projects?q=SEARCH_TERM&limit=5&page=1"

Each result has: uid, chainID, details.title, details.slug, details.description

Get Project by UID or Slug

curl -s -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0" \
  "${BASE_URL}/v2/projects/PROJECT_UID_OR_SLUG"

Get Project Grants

curl -s -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0" \
  "${BASE_URL}/v2/projects/PROJECT_UID_OR_SLUG/grants"

Each grant has: uid, details.title, milestones[]

Search Communities

curl -s -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0" \
  "${BASE_URL}/v2/communities/?limit=5&page=1"

Get Community Programs

curl -s -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0" \
  "${BASE_URL}/communities/COMMUNITY_SLUG_OR_UID/programs"

Each program has: programId, metadata.title. Always include programId when the user mentions a specific program.

Community Payouts

This is the primary endpoint for payout and invoice queries. Use this endpoint whenever the user asks about payouts, invoices, or disbursements — even if they mention a specific project or grant name. Use the search param to filter by name. Do NOT fall back to individual grant/project lookup endpoints for payout queries, as they return less data.

curl -s "${BASE_URL}/v2/communities/${COMMUNITY_UID}/payouts?page=1&limit=25" \
  -H "x-api-key: ${API_KEY}" \
  -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0"

Display rules (MANDATORY):

• Each item in payload[] represents a different project+grant combination
• The first column in every table MUST be Project (from item.project.title)
• The second column MUST be Grant (from item.grant.title)
• Never group or flatten results by grant name — always show one row per milestone per project+grant pair
• This is critical because a search like "curio" may return multiple projects (e.g., "Curio Storage" and "Curio Dashboard") and the user needs to tell them apart

Optional query params:

Requires COMMUNITY_VIEW permission. If 403, try the public endpoint:

curl -s "${BASE_URL}/v2/communities/${COMMUNITY_UID}/payouts/public?page=1&limit=25" \
  -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0"

The public endpoint requires no auth but returns fewer fields (sensitive data stripped).

Grant Payout History

Get disbursement history for a specific grant.

curl -s "${BASE_URL}/v2/payouts/grant/${GRANT_UID}/history?page=1&limit=20" \
  -H "x-api-key: ${API_KEY}" \
  -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0"

Grant Total Disbursed

Get the total amount already paid out for a grant.

curl -s "${BASE_URL}/v2/payouts/grant/${GRANT_UID}/total-disbursed" \
  -H "x-api-key: ${API_KEY}" \
  -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0"

Pending Disbursements

List disbursements awaiting processing for a community.

curl -s "${BASE_URL}/v2/payouts/community/${COMMUNITY_UID}/pending?page=1&limit=20" \
  -H "x-api-key: ${API_KEY}" \
  -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0"

Payout Config for a Grant

Get the payout configuration (payment address, token, schedule) for a grant.

curl -s "${BASE_URL}/v2/payout-config/grant/${GRANT_UID}" \
  -H "x-api-key: ${API_KEY}" \
  -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0"

Grant Invoices

List all milestone invoices for a grant.

curl -s "${BASE_URL}/v2/milestone-invoices/grant/${GRANT_UID}" \
  -H "x-api-key: ${API_KEY}" \
  -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0"

Each invoice has: id, grantUID, milestoneUID, milestoneLabel, invoiceStatus (not_submitted, submitted, received, paid), invoiceReceivedAt, invoiceFileKey

Invoice Download

Get a temporary download URL for an invoice file (15 min TTL). Requires the invoiceFileKey from the grant invoices response.

curl -s "${BASE_URL}/v2/milestone-invoices/download?key=${INVOICE_FILE_KEY}" \
  -H "x-api-key: ${API_KEY}" \
  -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0"

Returns: { "downloadUrl": "..." }

Natural Language Mapping

Error Handling

Edge Cases