feat: restructure Karma agent skills

.claude-plugin/marketplace.json

@@ -5,54 +5,25 @@
     "url": "https://karmahq.xyz"
   },
   "metadata": {
-    "description": "Agent skills for the Karma ecosystem — manage projects, grants, milestones, and discover funding opportunities",
-    "version": "1.0.0"
+    "description": "Shared Karma agent skills for product chat, external agents, and MCP-capable runtimes",
+    "version": "3.0.0"
   },
   "plugins": [
     {
-      "name": "Find Funding Opportunities",
-      "description": "Search the Karma Funding Map for grants, hackathons, bounties, accelerators, VC funds, and RFPs",
-      "version": "1.2.0",
+      "name": "Karma Agent Skills",
+      "description": "Use Karma knowledge, project, program, review, and philanthropy workflows through a runtime-provided operation surface.",
+      "version": "3.0.0",
       "source": "./",
       "strict": false,
-      "tags": ["discovery", "funding", "grants"],
+      "tags": ["karma", "projects", "programs", "review", "philanthropy"],
       "skills": [
-        "./skills/find-funding-opportunities"
-      ]
-    },
-    {
-      "name": "Project Manager",
-      "description": "Create and manage projects, grants, milestones, and updates on the Karma protocol",
-      "version": "1.0.0",
-      "source": "./",
-      "strict": false,
-      "tags": ["agent", "projects", "grants", "attestations"],
-      "skills": [
-        "./skills/setup-agent",
-        "./skills/project-manager"
-      ]
-    },
-    {
-      "name": "Funding Program Manager",
-      "description": "Manage funding programs — reviewers, applications, milestones, payouts, grant agreements, and AI evaluation",
-      "version": "1.0.0",
-      "source": "./",
-      "strict": false,
-      "tags": ["program", "admin", "reviewer", "payout", "application"],
-      "skills": [
-        "./skills/setup-agent",
-        "./skills/funding-program-manager"
-      ]
-    },
-    {
-      "name": "Skill Creator",
-      "description": "Create new Claude Code skills for the Karma ecosystem",
-      "version": "0.1.0",
-      "source": "./",
-      "strict": false,
-      "tags": ["development", "skills"],
-      "skills": [
-        "./skills/skill-creator"
+        "./skills/knowledge-base-answering",
+        "./skills/karma-product-concepts",
+        "./skills/application-review",
+        "./skills/milestone-review",
+        "./skills/program-admin-workspace",
+        "./skills/project-owner-workspace",
+        "./skills/philanthropy-research"
       ]
     }
   ]

.claude-plugin/plugin.json

@@ -1,13 +1,12 @@
 {
   "name": "karma",
-  "description": "Find funding opportunities, manage projects, grants, milestones, and updates on the Karma protocol",
-  "version": "2.1.0",
+  "description": "Shared Karma agent skills for product chat, external agents, and MCP-capable runtimes",
+  "version": "3.0.0",
   "author": {
     "name": "Karma",
     "url": "https://karmahq.xyz"
   },
   "repository": "https://github.com/show-karma/skills",
   "license": "MIT",
-  "keywords": ["grants", "funding", "projects", "milestones", "web3", "attestations"],
-  "hooks": "./hooks/hooks.json"
+  "keywords": ["karma", "grants", "funding", "projects", "milestones", "review", "philanthropy"]
 }

README.md

@@ -1,64 +1,64 @@
 # Karma Skills
 
-Agent skills for the Karma ecosystem — find funding opportunities, create and manage projects, administer funding programs, and post milestones and updates.
+Shared agent skills for the Karma ecosystem.
+
+These skills describe Karma workflows and operation names. They do not include API-key setup, curl examples, or raw endpoint instructions. The runtime is responsible for exposing the operations listed in each skill, whether through Karma's in-product MCP server or an external adapter.
 
 ## Quick Start
 
 ```bash
 npx skills add show-karma/skills
 ```
 
-Then ask your agent:
-
-> Create a project called "My DeFi App" on Optimism
+Then ask your agent questions such as:
 
-> Find active grant programs on Ethereum
+> How do I submit a milestone update for this program?
 
-> Post an update on my project — we shipped the MVP
+> What applications do I need to review?
 
-> List reviewers for Optimism Audit Grants Season 8
+> Which projects have milestones ready for my review?
 
-> Show pending applications for my grant program
+> What is happening across the programs I manage?
 
-> Add a reviewer to my program
+> What is the status of my project milestones?
 
 ## What Are Skills?
 
-Skills are reusable instruction sets that encode domain expertise into repeatable workflows. Each skill teaches an AI agent how to perform a specific task within the Karma ecosystem. Skills work with any compatible agent client, including Claude Code, Cursor, Windsurf, and others.
+Skills are reusable instruction sets that encode domain expertise into repeatable workflows. Each skill teaches an AI agent how to perform a specific task within the Karma ecosystem.
 
 The `SKILL.md` file contains YAML frontmatter (name, description, version, tags) followed by the instructions agents will follow.
 
 ## Available Skills
 
 | Skill | Description |
 |-------|-------------|
-| [`setup-agent`](skills/setup-agent/) | Register and get your API key — quick start (no account), email login, or manual. Saves key to shell config. |
-| [`project-manager`](skills/project-manager/) | Create and manage projects, grants, milestones, and updates on-chain. Handles all attestation actions in one skill. |
-| [`funding-program-manager`](skills/funding-program-manager/) | Administer a funding program — manage reviewers, applications, milestones, payouts, grant agreements, and AI evaluations. |
-| [`find-funding-opportunities`](skills/find-funding-opportunities/) | Search the Karma Funding Map for grants, hackathons, bounties, accelerators, VC funds, and RFPs. |
-
-All on-chain skills use the Karma Agent API with a server-side wallet. No gas fees, no browser wallet needed.
+| Skill | Description |
+|-------|-------------|
+| [`knowledge-base-answering`](skills/knowledge-base-answering/) | Answer community and program process questions from indexed knowledge-base content. |
+| [`karma-product-concepts`](skills/karma-product-concepts/) | Explain Karma roles, entities, and routing between entity data and knowledge-base content. |
+| [`application-review`](skills/application-review/) | Help application reviewers find assigned applications and review state. |
+| [`milestone-review`](skills/milestone-review/) | Help milestone reviewers find projects and milestones ready for review. |
+| [`program-admin-workspace`](skills/program-admin-workspace/) | Help admins inspect programs, applications, reviewers, milestones, payouts, and reports. |
+| [`project-owner-workspace`](skills/project-owner-workspace/) | Help project owners inspect projects, grants, milestones, completions, updates, indicators, invoices, and payouts. |
+| [`philanthropy-research`](skills/philanthropy-research/) | Research grantmakers, nonprofits, grant transactions, totals, filings, and prospect-fit evidence. |
 
 ## How It Works
 
 ```
-You
-  ↓
-AI Agent (picks the right skill)
+User request
   ↓
-Karma API (encodes attestation)
+AI agent selects a Karma skill
   ↓
-Server Wallet (signs + submits tx, gasless)
+Skill names the workflow and expected operations
   ↓
-Blockchain (EAS attestation created)
+Runtime adapter exposes operations through MCP or another interface
   ↓
-karmahq.xyz (visible on the web)
+Karma services enforce auth, RBAC, budgets, and tool policy
 ```
 
-- **No gas fees** — transactions are sponsored via account abstraction
-- **No browser wallet** — your agent gets a server-side wallet
-- **On-chain** — every action creates a verifiable [EAS attestation](https://docs.attest.sh/)
-- **Client-agnostic** — works with any AI agent that supports the Skills Standard
+- **Skills are transport-neutral** — no raw endpoint or API-key setup instructions.
+- **Runtime enforcement stays in code** — skills guide behavior but do not grant permissions.
+- **Client-agnostic** — compatible agents can install the same skill files.
 
 ## Skill Format
 
@@ -71,6 +71,8 @@ skills/my-skill/
 └── assets/           # Templates, scripts (optional)
 ```
 
+Karma-specific frontmatter may include `operations`, a list of runtime operation names the skill expects.
+
 ## Karma Ecosystem
 
 [Karma](https://www.karmahq.xyz) helps projects build reputation and find funding opportunities. Karma's grants platform can be used by organizations to run their grant program (application intake, funds disbursal, milestone and metrics tracking). Key areas:

generated/tools-manifest.json

@@ -0,0 +1,27 @@
+{
+  "version": "mvp",
+  "tools": [
+    { "name": "search_knowledge_base", "kind": "read" },
+    { "name": "get_my_workspace", "kind": "read" },
+    { "name": "list_my_grants", "kind": "read" },
+    { "name": "get_project_details", "kind": "read" },
+    { "name": "get_project_status", "kind": "read" },
+    { "name": "list_project_milestones", "kind": "read" },
+    { "name": "list_assigned_applications", "kind": "read" },
+    { "name": "get_application_details", "kind": "read" },
+    { "name": "preview_add_application_comment", "kind": "preview" },
+    { "name": "commit_add_application_comment", "kind": "commit" },
+    { "name": "list_milestone_completions", "kind": "read" },
+    { "name": "list_pending_milestones", "kind": "read" },
+    { "name": "get_milestone_completion", "kind": "read" },
+    { "name": "list_program_applications", "kind": "read" },
+    { "name": "get_program_financials", "kind": "read" },
+    { "name": "preview_generate_portfolio_report", "kind": "preview" },
+    { "name": "commit_generate_portfolio_report", "kind": "commit" },
+    { "name": "search_organizations", "kind": "read" },
+    { "name": "search_grants", "kind": "read" },
+    { "name": "aggregate_grants", "kind": "read" },
+    { "name": "get_irs_990", "kind": "read" },
+    { "name": "run_sql", "kind": "read" }
+  ]
+}

skill-profiles/anonymous/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "karma-in-product-anonymous",
+  "description": "Anonymous-safe Karma skills for in-product chat",
+  "version": "0.1.0",
+  "author": {
+    "name": "Karma",
+    "url": "https://karmahq.xyz"
+  },
+  "repository": "https://github.com/show-karma/skills",
+  "license": "MIT",
+  "keywords": ["karma", "knowledge-base", "public-chat"]
+}

skill-profiles/anonymous/skills/knowledge-base-answering/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: knowledge-base-answering
+description: Answer public program and community process questions from Karma knowledge-base content.
+operations:
+  - search_knowledge_base
+---
+
+# Knowledge Base Answering
+
+Use this skill for procedural, conceptual, or operational questions about a specific community, program, guide, policy, eligibility rule, deadline, or process.
+
+Call `search_knowledge_base` before answering. For how-to or step-by-step questions, set `topK` to 8 on the first search.
+
+If results exist, answer from the retrieved chunks. Cite the `source` URL for each fact when a source is present. Attach a source only to facts that came from that same result.
+
+If no results exist, say the topic is not covered in the community knowledge base. Do not answer from general knowledge for community-specific process questions.
+
+Do not begin with a source preamble like "Based on the knowledge base" or "According to the docs." The first sentence should answer the question directly.
+
+For procedural answers, list all retrieved steps in source order as a numbered list. Do not replace the answer with only a link to the guide.
+
+Do not direct users to generic Karma support channels. If a program-specific contact channel appears in retrieved chunks, use that. Otherwise say the knowledge base does not include a contact for that question.

skill-profiles/authenticated/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "karma-in-product-authenticated",
+  "description": "Authenticated Karma skills for in-product chat",
+  "version": "0.1.0",
+  "author": {
+    "name": "Karma",
+    "url": "https://karmahq.xyz"
+  },
+  "repository": "https://github.com/show-karma/skills",
+  "license": "MIT",
+  "keywords": ["karma", "projects", "programs", "review"]
+}

skill-profiles/authenticated/skills/application-review/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: application-review
+description: Help application reviewers find assigned applications and understand review state.
+operations:
+  - list_assigned_applications
+  - get_application_details
+  - preview_add_application_comment
+  - commit_add_application_comment
+---
+
+# Application Review
+
+Use this skill when a reviewer asks about applications assigned to them, pending review work, review comments, application status, applicants, or links to applications.
+
+For "what applications do I need to review" or similar queue questions, call `list_assigned_applications` or the available workspace tool before answering. Return application identifiers, project or applicant names, statuses, and links when the tool provides them.
+
+If the tool result does not include links, do not invent links. Say what identifiers are available and offer to open or fetch details for a specific application if the tool surface supports it.
+
+For comments or feedback, confirm the exact text with the user before submitting it. Never claim a comment was posted unless the write tool succeeds.
+
+Do not use the knowledge base for application records or reviewer queues.

skill-profiles/authenticated/skills/karma-product-concepts/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: karma-product-concepts
+description: Explain Karma roles, entity relationships, and when to use entity data versus knowledge-base content.
+operations: []
+---
+
+# Karma Product Concepts
+
+Use this skill when the user asks what a Karma role, entity, or responsibility means.
+
+Karma is a registry of funded work. Communities run programs. Programs receive applications. Approved applications become projects and may have grants, payouts, milestones, updates, invoices, and indicators.
+
+Applications are submissions awaiting a decision. Projects are funded or registered work after approval. Grants are allocations. Payouts are money movements against grants. Milestones track delivery. Indicators are metrics on projects.
+
+For questions about entity records, use entity tools rather than the knowledge base. Examples include which projects exist, who received funding, application or grant status, milestone status, payout history, project metrics, or reviewer queues. Ground names, dates, amounts, statuses, metrics, and links in tool results from this turn.
+
+For questions about community or program process, rules, policies, or guides, use the knowledge-base skill.
+
+Roles:
+
+- Applicant or project owner: submits applications, manages funded projects, posts updates, tracks milestones, and reports impact.
+- Application reviewer: reviews assigned applications and leaves feedback. Reviewers advise; program admins make final decisions.
+- Milestone reviewer: verifies submitted milestone completions and requests changes when evidence is insufficient. This is distinct from application review.
+- Program or community admin: runs programs, configures intake, manages reviewers, decides application outcomes, oversees milestones, payouts, agreements, and reports.
+
+When the user asks about their own responsibilities, scope the answer to the role and resources available in the current conversation.

skill-profiles/authenticated/skills/knowledge-base-answering/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: knowledge-base-answering
+description: Answer program and community process questions from Karma knowledge-base content.
+operations:
+  - search_knowledge_base
+---
+
+# Knowledge Base Answering
+
+Use this skill for procedural, conceptual, or operational questions about a specific community, program, guide, policy, eligibility rule, deadline, or process.
+
+Call `search_knowledge_base` before answering. For how-to or step-by-step questions, set `topK` to 8 on the first search.
+
+If results exist, answer from the retrieved chunks. Cite the `source` URL for each fact when a source is present. Attach a source only to facts that came from that same result.
+
+If no results exist, say the topic is not covered in the community knowledge base. Do not answer from general knowledge for community-specific process questions.
+
+Do not begin with a source preamble like "Based on the knowledge base" or "According to the docs." The first sentence should answer the question directly.
+
+For procedural answers, list all retrieved steps in source order as a numbered list. Do not replace the answer with only a link to the guide.
+
+Do not direct users to generic Karma support channels. If a program-specific contact channel appears in retrieved chunks, use that. Otherwise say the knowledge base does not include a contact for that question.

skill-profiles/authenticated/skills/milestone-review/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: milestone-review
+description: Help milestone reviewers find projects and milestones ready for review.
+operations:
+  - get_my_workspace
+  - list_milestone_completions
+  - list_pending_milestones
+  - get_milestone_completion
+  - get_project_details
+  - list_project_milestones
+---
+
+# Milestone Review
+
+Use this skill when a milestone reviewer asks which projects, grants, milestones, or completions are ready for their review.
+
+Call the available milestone review queue, milestone completion, pending milestone, or workspace tool before answering. Return project names, milestone titles, submitted completion state, due dates, and links when the tool provides them.
+
+If only project or milestone identifiers are available, present those identifiers clearly and avoid inventing missing names, links, or statuses.
+
+Milestone review is about verifying completion evidence. It is not the same as reviewing applications.
+
+Do not use the knowledge base for milestone queues or completion status.