project-manager

Project Manager

Manage projects, grants, milestones, and updates on the Karma protocol. All actions create on-chain attestations via a single API.

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, skip to Verify.

Otherwise use the AskUserQuestion tool with these options:

• Question: "You need a Karma API key to continue. How would you like to set it up?"
• Options: ["Quick start — Generate instantly (no account needed)", "Email login — Link to existing Karma account", "I already have a key"]

Quick Start (No Account Needed)

curl -s -X POST "${BASE_URL}/v2/agent/register" \
  -H "Content-Type: application/json" \
  -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0" \
  -d '{}'

Returns { "apiKey": "karma_..." } — shown only once.

Important: Always send -d '{}' — an empty body causes a 400 error.

Email Login

1. Ask for email
2. POST ${BASE_URL}/v2/api-keys/auth/init with { "email": "..." }
3. Ask for code → POST ${BASE_URL}/v2/api-keys/auth/verify with { "email": "...", "code": "...", "name": "claude-agent" }
4. Returns { "key": "karma_..." }

Save API Key

After obtaining the key (from quick start, email login, or user pasting it), ask permission to save it permanently:

Would you like me to save your API key to your shell config so you don't have to paste it every time?

If yes, detect the user's shell and append the export:

# Detect shell config file
if [ -f "$HOME/.zshrc" ]; then
  SHELL_RC="$HOME/.zshrc"
elif [ -f "$HOME/.bashrc" ]; then
  SHELL_RC="$HOME/.bashrc"
fi

# Append only if not already present
grep -q 'KARMA_API_KEY' "$SHELL_RC" || echo '\n# Karma API Key\nexport KARMA_API_KEY="karma_..."' >> "$SHELL_RC"

# Also export for current session
export KARMA_API_KEY="karma_..."

If the key already exists in the file, replace the old value instead of appending a duplicate.

If the user declines, just set it for the current session:

export KARMA_API_KEY="karma_..."

Verify

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 response includes walletAddress and supportedActions → ready. Do NOT show wallet/chain details to the user. Tell them:

Your Karma agent is ready! You can now create projects, grants, milestones, and post updates.

---

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}
- Chain: {chainName} ({chainId})
- Transaction: {transactionHash}

---

Supported Chains

Default Chain Behavior

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

Your project will be created on Base. Continue?

• Yes
• Choose another chain: Arbitrum, Base, Celo, Lisk, Optimism, Polygon, Scroll, Sei

Chain Inheritance

Child attestations must use the same chain 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 chain from the API — never ask the user for a chain on child attestations.

---

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}
• Chain: {chainName} ({chainId})
• Transaction: {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 — fetch current details first for partial updates.

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: Fetch current grant details first, merge user's changes with existing values, then send all fields.

---

completeGrant

Mark a grant as fully completed with a final summary.

After completion:

Grant {title} has been marked as completed!

• Grant: {title}
• Chain: {chainName} ({chainId})
• Transaction: {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.

---

Natural Language Mapping

---

Error Handling

Edge Cases