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..d28bd5b --- /dev/null +++ b/plugins/shared/skills/resources/SKILL.md @@ -0,0 +1,76 @@ +--- +name: resources +description: > + 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. +--- + +# 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. Resource Clients (for app code) + +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 + +**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 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. + +**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