From 3dc215457a51e8583db396fffde5ad78dae96fa1 Mon Sep 17 00:00:00 2001 From: josegironn <30703536+josegironn@users.noreply.github.com> Date: Thu, 9 Apr 2026 15:26:11 -0700 Subject: [PATCH 1/2] feat: add resources hub skill for progressive disclosure Adds a top-level `resources` skill that explains the resource interaction model (MCP tools, TypeScript clients, write safety) and provides a directory of all resource-specific skills. Updates the `major` skill to point to it and adds a cross-reference from `resources_list-resources`. Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude-plugin/marketplace.json | 2 +- plugins/major/skills/major/SKILL.md | 3 +- plugins/major/skills/resources | 1 + plugins/shared/skills/resources/SKILL.md | 86 +++++++++++++++++++ .../skills/resources_list-resources/SKILL.md | 2 + 5 files changed, 92 insertions(+), 2 deletions(-) create mode 120000 plugins/major/skills/resources create mode 100644 plugins/shared/skills/resources/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 42f695a..6dfa0bd 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -13,7 +13,7 @@ "name": "major", "source": "./plugins/major", "description": "Use the Major platform agentically via Claude Code", - "version": "1.0.4" + "version": "1.0.5" } ] } diff --git a/plugins/major/skills/major/SKILL.md b/plugins/major/skills/major/SKILL.md index 6c7d2b4..e3f2d98 100644 --- a/plugins/major/skills/major/SKILL.md +++ b/plugins/major/skills/major/SKILL.md @@ -100,7 +100,7 @@ Major is a platform for building and deploying Next.js web applications. It crea 5. **App type**: Creates a Next.js application by default -6. **Resource management**: Use `major resource list` to see available resources, then `major resource add --id ` or `major resource remove --id ` to manage them programmatically. Use `major resource env-list --json` to see environments and `major resource env --id ` to switch. +6. **Resource management**: Use `major resource list` to see available resources, then `major resource add --id ` or `major resource remove --id ` to manage them programmatically. Use `major resource env-list --json` to see environments and `major resource env --id ` to switch. To learn how resources work in code (MCP tools, generated clients, write safety), load the `resources` skill. 7. **Organization selection**: Use `major org list --json` to get org IDs, then `major org select --id ` to switch orgs programmatically. @@ -111,5 +111,6 @@ For detailed workflows, see the docs below: - [Getting Started](docs/getting-started.md) -- Install, auth, first app - [App Workflows](docs/app-workflows.md) -- Create, clone, start, deploy - [Resource Workflows](docs/resource-workflows.md) -- Create, manage, environments +- **Resources in Code** -- Load the `resources` skill for interacting with resources from code (MCP tools, TypeScript clients, safety rules) - [Org Management](docs/org-management.md) -- Organizations and teams - [Troubleshooting](docs/troubleshooting.md) -- Common issues and fixes diff --git a/plugins/major/skills/resources b/plugins/major/skills/resources new file mode 120000 index 0000000..860b645 --- /dev/null +++ b/plugins/major/skills/resources @@ -0,0 +1 @@ +../../shared/skills/resources \ No newline at end of file diff --git a/plugins/shared/skills/resources/SKILL.md b/plugins/shared/skills/resources/SKILL.md new file mode 100644 index 0000000..c9fbc1c --- /dev/null +++ b/plugins/shared/skills/resources/SKILL.md @@ -0,0 +1,86 @@ +--- +name: resources +description: > + How resources work on the Major platform -- two access modes (MCP tools and TypeScript clients), + security rules, write operation safety, and a directory of all resource-specific skills. + Load this skill when working with any resource or when you need to understand the resource model. +--- + +# Resources + +Resources are external services (databases, APIs, storage) connected to Major apps through the platform's secure proxy. They are managed at the organization level and attached to individual apps. + +## Discovery + +Before working with any resource, discover what's available. Load the `resources_list-resources` skill for the full discovery workflow, including reading context documents the user has attached. + +Quick start: call `mcp__resources__list_resources` to list all resources the app has access to. + +## Two Access Modes + +### 1. MCP Tools (direct, no code needed) + +Tools follow the pattern `mcp__resources___`. Use these for ad-hoc exploration, queries, and operations during your session. + +Example: `mcp__resources__postgresql_query`, `mcp__resources__s3_list_objects` + +### 2. Generated TypeScript Clients (for app code) + +Call `mcp__resource-tools__add-resource-client` with a `resourceId` to generate a typed client. Clients are created in `/clients/` (Next.js) or `/src/clients/` (Vite). + +```typescript +import { dbClient } from "./clients"; + +const result = await dbClient.query({ sql: "SELECT * FROM users" }, "list-users"); +if (result.ok) { + const rows = result.result; +} +``` + +## Rules + +**Security**: +- Never connect directly to databases or APIs. Never use credentials in code. +- Always use generated clients or MCP tools. + +**Client usage**: +- **Do NOT guess client method names or signatures.** Always read the generated client source in `/clients/` to verify available methods and their exact signatures. +- Next.js: resource clients must be used in server-side code only (Server Components, Server Actions, API Routes). Vite: call directly from frontend. +- Always check `result.ok` before accessing `result.result`. +- Invocation keys must be static strings (e.g., `"fetch-user-orders"`), never dynamic values. + +**Write operation safety**: +- Write operations (create, update, delete records; send messages; run mutations) can have real-world consequences. +- Always confirm with the user before performing write operations on production resources. +- For destructive operations (DELETE, DROP, truncate), require explicit user confirmation and state what will be affected. +- Prefer read-only exploration first (list, describe, query) before any writes. + +## Resource Skills Directory + +Load the specific skill for the resource type you're working with: + +| Skill | Resource | Description | +|-------|----------|-------------| +| `resources_postgresql` | PostgreSQL | SQL queries, migrations, psql | +| `resources_mssql` | SQL Server | T-SQL queries, schema exploration | +| `resources_snowflake` | Snowflake | Warehouse queries, schema exploration | +| `resources_bigquery` | BigQuery | SQL queries, dataset/table operations | +| `resources_neo4j` | Neo4j | Cypher queries, graph traversal | +| `resources_dynamodb` | DynamoDB | Queries, scans, CRUD operations | +| `resources_cosmosdb` | CosmosDB | Container queries, CRUD, patch operations | +| `resources_managed-database` | Managed DB | Major-hosted PostgreSQL setup | +| `resources_s3` | Amazon S3 | Object operations, presigned URLs, uploads | +| `resources_salesforce` | Salesforce | SOQL queries, sObject CRUD | +| `resources_hubspot` | HubSpot | Contacts, companies, deals | +| `resources_quickbooks` | QuickBooks | Invoices, customers, accounts | +| `resources_outreach` | Outreach | Prospects, sequences | +| `resources_slack` | Slack | Messaging, channel operations | +| `resources_googlesheets` | Google Sheets | Reading, writing, formatting | +| `resources_google-analytics` | Google Analytics | GA4 reports, account management | +| `resources_googlecalendar` | Google Calendar | Events, calendar management | +| `resources_lambda` | AWS Lambda | Function invocation, management | +| `resources_graphql` | GraphQL | Queries, mutations, introspection | +| `resources_custom-api` | Custom API | HTTP requests with auto auth | +| `resources_ai-proxy` | AI Proxy | Built-in LLM proxy (Anthropic/OpenAI) | +| `resources_majorauth` | Major Auth | Share/revoke app access by email | +| `resources_list-resources` | Discovery | List resources, read context docs | diff --git a/plugins/shared/skills/resources_list-resources/SKILL.md b/plugins/shared/skills/resources_list-resources/SKILL.md index 285be62..222ee74 100644 --- a/plugins/shared/skills/resources_list-resources/SKILL.md +++ b/plugins/shared/skills/resources_list-resources/SKILL.md @@ -5,6 +5,8 @@ description: Use this skill whenever you need to discover or work with resources # Discovering and Using Resources +> For the complete resource interaction model (MCP tools, TypeScript clients, write safety, security rules), load the `resources` skill. + The application has been granted access to resources — external services (databases, APIs, storage, etc.) that your application can interact with through Major's secure clients. ## Step 1: List available resources From c9d769357152259a802be3e805ccc2e2238532d7 Mon Sep 17 00:00:00 2001 From: josegironn <30703536+josegironn@users.noreply.github.com> Date: Thu, 9 Apr 2026 17:40:42 -0700 Subject: [PATCH 2/2] fix: reframe resource clients as app-level concept, not CLI-specific The TypeScript client section now describes resource clients as the way apps communicate with resources, deferring implementation details to the individual resource skills. Co-Authored-By: Claude Opus 4.6 (1M context) --- plugins/shared/skills/resources/SKILL.md | 18 ++++-------------- 1 file changed, 4 insertions(+), 14 deletions(-) diff --git a/plugins/shared/skills/resources/SKILL.md b/plugins/shared/skills/resources/SKILL.md index c9fbc1c..d28bd5b 100644 --- a/plugins/shared/skills/resources/SKILL.md +++ b/plugins/shared/skills/resources/SKILL.md @@ -1,7 +1,7 @@ --- name: resources description: > - How resources work on the Major platform -- two access modes (MCP tools and TypeScript clients), + How resources work on the Major platform -- two access modes (MCP tools and resource clients), security rules, write operation safety, and a directory of all resource-specific skills. Load this skill when working with any resource or when you need to understand the resource model. --- @@ -24,18 +24,9 @@ Tools follow the pattern `mcp__resources___`. Use these Example: `mcp__resources__postgresql_query`, `mcp__resources__s3_list_objects` -### 2. Generated TypeScript Clients (for app code) +### 2. Resource Clients (for app code) -Call `mcp__resource-tools__add-resource-client` with a `resourceId` to generate a typed client. Clients are created in `/clients/` (Next.js) or `/src/clients/` (Vite). - -```typescript -import { dbClient } from "./clients"; - -const result = await dbClient.query({ sql: "SELECT * FROM users" }, "list-users"); -if (result.ok) { - const rows = result.result; -} -``` +Each resource attached to an app has a typed client that your application code uses to communicate with it. These clients handle authentication and connection details automatically -- you never use credentials directly in code. Load the resource-specific skill (see directory below) for client usage details, method signatures, and examples. ## Rules @@ -44,8 +35,7 @@ if (result.ok) { - Always use generated clients or MCP tools. **Client usage**: -- **Do NOT guess client method names or signatures.** Always read the generated client source in `/clients/` to verify available methods and their exact signatures. -- Next.js: resource clients must be used in server-side code only (Server Components, Server Actions, API Routes). Vite: call directly from frontend. +- **Do NOT guess client method names or signatures.** Always read the client source to verify available methods and their exact signatures. - Always check `result.ok` before accessing `result.result`. - Invocation keys must be static strings (e.g., `"fetch-user-orders"`), never dynamic values.