@salesforce/afv-skills 1.22.0 → 1.23.0

package/skills/getting-metadata-api-context/references/usage_guide.md

@@ -1,420 +0,0 @@
-# Metadata API Skill — Usage Guide
-
-Supplementary reference material for the `getting-metadata-api-context` skill. Load this file only when you need the deeper background below; the core decision tree, section-loading rules, generation requirements, and troubleshooting live in `SKILL.md`.
-## Why Token Optimization Matters
-
-### Context Window Constraints
-
-Claude has a finite context window (200K tokens). Loading the full metadata-type corpus would consume:
-
-- **~15MB of JSON data**
-- **~75,000 tokens** (approximately 40% of available context)
-- **Reduced space** for your actual code and conversation
-
-This leaves less room for:
-- Your project's code files
-- Conversation history
-- Generated responses
-- Multi-turn problem solving
-
-### Cost Implications
-
-Token usage directly impacts costs:
-
-- **Input tokens**: Every loaded file counts toward input cost
-- **Repeated requests**: Loading files multiple times multiplies costs
-- **Cache misses**: Large contexts may not fit in prompt cache
-
-### Performance Trade-offs
-
-Loading all files affects performance:
-
-- **Slower response times**: More tokens to process
-- **Reduced relevance**: LLM must search through more irrelevant data
-- **Context dilution**: Important information gets buried in noise
-
-### Best Practices
-
-✅ **DO**:
-- **Use programmatic JSON parsing** to extract only needed sections (Python json.load(), Node.js JSON.parse(), etc.)
-- **Load only specific sections** from each JSON file (fields, description) not the entire file
-- Load 1-5 specific metadata types relevant to your task
-- Check the `sections` array first to see what's available
-- Use the index table to find related types
-- Skip WSDL segments and sample definitions unless explicitly needed
-- Cache frequently used sections (fields for CustomObject, Flow, Profile)
-
-❌ **DON'T**:
-- **NEVER use the `read_file` tool or other whole-file readers on the metadata-type JSON files** (loads entire file into context)
-- Load entire JSON files when you only need 1-2 sections
-- Load every metadata type at once
-- Load files "just in case" you might need them
-- Repeatedly load the same files in a conversation
-- Include WSDL segments unless you need schema validation
-- Load declarative_metadata_sample_definition unless examples are required
-
-### Example: Good vs. Bad
-
-**Bad** (wastes ~75,000 tokens):
-```text
-"Load all metadata types so I can reference them"
-```
-
-**Better** (uses ~500 tokens):
-```text
-"Show me the CustomObject and CustomField metadata types"
-```
-
-**Best** (uses ~150 tokens):
-```text
-"Show me only the 'fields' section from CustomObject.json"
-```
-
-The section-specific approach uses **500x fewer tokens** while providing exactly what you need.
-## Token Size Reference
-
-Approximate token counts for different loading strategies:
-
-| What You Load | Approx. Tokens | Use Case |
-|---------------|----------------|----------|
-| Single section (fields only) | 50-200 | ✅ **BEST** - Quick field reference |
-| Single section (description) | 20-100 | ✅ Overview/understanding |
-| 2-3 sections from one type | 150-500 | Most common use case |
-| Entire single type (small) | 100-500 | Small types without WSDL |
-| Entire single type (large) | 500-2,000 | ❌ **Wasteful** - includes unused WSDL |
-| 5 related types (entire files) | 2,000-5,000 | ❌ Use section-specific loading instead |
-| 20 types (entire files) | 10,000-15,000 | ❌ Avoid - major waste |
-| 50 types (entire files) | 25,000-35,000 | ❌ Never do this |
-| The full metadata-type corpus | ~75,000 | ❌ Catastrophic waste |
-
-**Note**: Loading only specific sections (fields, description) typically reduces token usage by **60-80%** per file compared to loading entire files with WSDL segments and examples.
-## Usage Examples
-
-### Example 1: Creating a CustomObject (Section-Specific)
-
-**User**: "I need to create a custom object metadata file for a Student object"
-
-**Response approach** (Token-efficient):
-1. Load ONLY the `fields` section from `data/metadata_api/CustomObject.json`
-2. Review required fields: `label`, `nameField`, `deploymentStatus`, `sharingModel`
-3. If needed, also load the `declarative_metadata_sample_definition` section for XML structure example
-4. Generate XML with correct namespace
-5. Include file naming convention: `Student__c.object-meta.xml`
-
-**Token savings**: ~70% (loading only 'fields' + 'declarative_metadata_sample_definition' instead of entire file with WSDL)
-
-### Example 2: Understanding Flow Metadata (Section-Specific)
-
-**User**: "What fields are available in a Flow metadata type?"
-
-**Response approach** (Token-efficient):
-1. Load ONLY the `fields` section from `data/metadata_api/Flow.json`
-2. List field names, types, and descriptions
-3. Highlight required fields and common patterns
-4. Skip `wsdl_segment`, `description`, and other sections
-
-**Token savings**: ~80% (fields section is ~200 tokens vs ~1000 for entire file)
-
-### Example 3: Modifying a Profile (Section-Specific)
-
-**User**: "How do I add object permissions to a Profile?"
-
-**Response approach** (Token-efficient):
-1. Load ONLY the `fields` section from `data/metadata_api/Profile.json`
-2. Find `objectPermissions` field definition within that section
-3. Show structure and required sub-fields
-4. If XML example needed, separately load `declarative_metadata_sample_definition`
-
-**Token savings**: ~75% (avoiding massive WSDL segment in Profile.json)
-
-### Example 4: Working with ApexClass Metadata (Section-Specific)
-
-**User**: "What's the metadata file structure for an Apex class?"
-
-**Response approach** (Token-efficient):
-1. Load the `fields` and `description` sections from `data/metadata_api/ApexClass.json`
-2. Show the simple structure (apiVersion, status)
-3. Explain the relationship between `.cls` and `.cls-meta.xml` files
-4. Load `file_information` section only if directory structure details needed
-
-**Token savings**: ~60% (ApexClass is simpler but still benefits from section filtering)
-## Common Workflows
-
-### Workflow 1: Creating New Metadata
-
-1. Identify the metadata type you need
-2. Load the corresponding JSON file
-3. Review required fields and their types
-4. Check sample XML in `declarative_metadata_sample_definition`
-5. Generate XML with correct namespace and structure
-6. Save to appropriate directory in SFDX project
-7. Validate with Salesforce CLI
-
-### Workflow 2: Understanding Existing Metadata
-
-1. Identify the metadata type from file extension
-2. Load the JSON documentation
-3. Review field descriptions to understand purpose
-4. Check WSDL segment for complex type definitions
-5. Cross-reference with your XML file
-
-### Workflow 3: Modifying Metadata
-
-1. Load JSON for the metadata type
-2. Identify the field you want to modify
-3. Verify it's not a required field or understand implications
-4. Check field type and valid values
-5. Update XML maintaining proper structure
-6. Validate before deploying
-
-### Workflow 4: Planning a Migration
-
-1. List all metadata types involved
-2. Load JSON for each type (5-10 at a time to optimize tokens)
-3. Identify dependencies between types
-4. Plan deployment order based on dependencies
-5. Validate required fields for each type
-## Understanding Sections
-
-Different metadata types have different available sections. Here's what each section typically contains:
-
-### Core Sections (Most Types)
-
-- **title**: The metadata type name and page header
-- **description**: Overview of what the metadata type represents and its purpose
-- **fields**: Detailed field definitions with types, descriptions, and requirements
-- **file_information**: File naming conventions and extensions
-- **directory_location**: Where files are stored in Salesforce DX projects
-
-### Schema Sections
-
-- **wsdl_segment**: XML schema definition from the Metadata API WSDL
-  - Contains complexType and simpleType definitions
-  - Shows complete structure and type relationships
-  - Useful for validation and understanding complex nested structures
-
-### Example Sections
-
-- **declarative_metadata_sample_definition**: Sample XML code
-  - Usually includes 1-3 complete examples
-  - Shows real-world usage patterns
-  - Demonstrates proper XML structure
-
-### Type-Specific Sections
-
-Some metadata types have additional sections:
-
-- **child_metadata_types**: Nested or related types (e.g., CustomObject has CustomField)
-- **fields_for_customfield**: Special field definitions for CustomField type
-- **countriesandstates**: Country and state data (AddressSettings)
-- **action_override_types**: Available override types (ActionOverride)
-
-#### `fields` vs `sub_types` — composite types
-
-Every authored metadata type exposes its OWN fields under a **`fields`** key.
-Composite types (Flow, Workflow, Layout, …) also reference distinct sub-types
-(their own complexTypes); those are grouped under a **`sub_types`** object keyed
-by the sub-type's CamelCase name — they are NOT mixed into the parent's `fields`.
-
-| Pattern | Where the fields live | Examples |
-|---|---|---|
-| Simple type | `fields` | ApexTrigger, ApexPage, StaticResource, RemoteSiteSetting |
-| Composite type | `fields` (the type's own fields) + `sub_types: { <CamelCaseName>: {…fields…} }` | `Flow` → `fields` + `sub_types.FlowActionCall`, `sub_types.FlowAssignment`, …; `Workflow` → `fields` + `sub_types.WorkflowAlert`, … |
-| SOAP result / response wrapper | `properties` (no `fields`) | SaveResult, UpsertResult, DeleteResult, Error |
-
-So for `Flow.json`: load **`fields`** for Flow's own fields (e.g. `actionCalls`,
-which is typed `FlowActionCall[]`), and load **`sub_types.FlowActionCall`** for
-that referenced type's fields (e.g. `actionName`). A sub-type's fields are NOT in
-the parent's `fields`. Feature-gated settings (e.g. IndustriesSettings'
-"Fields for Health Cloud" groups) are merged into the single `fields` section.
-
-See the [Index Table](metadata_index_table.md) for a complete breakdown of which types have which sections.
-
-## Metadata File Generation — Detailed Reference
-
-### Field Type Validation
-
-Match field types exactly:
-
-| Field Type | XML Format | Example |
-|------------|------------|---------|
-| `string` | `<fieldName>value</fieldName>` | `<label>My Object</label>` |
-| `boolean` | `<fieldName>true or false</fieldName>` | `<deploymentStatus>Deployed</deploymentStatus>` |
-| `int` | `<fieldName>123</fieldName>` | `<externalSharingModel>Private</externalSharingModel>` |
-| `CustomField[]` | Multiple `<fields>` tags | `<fields>...</fields><fields>...</fields>` |
-| `enumeration` | Use exact enum value | `<sharingModel>ReadWrite</sharingModel>` |
-
-### Common Patterns and Conventions
-
-#### File Naming
-
-- Custom objects: `MyObject__c.object-meta.xml`
-- Custom fields: `MyObject__c.MyField__c.field-meta.xml`
-- Flows: `My_Flow.flow-meta.xml`
-- Apex classes: `MyClass.cls-meta.xml`
-- Profiles: `Admin.profile-meta.xml`
-
-#### Two-File ("source + meta") Types
-
-Several metadata types are authored as **a pair** of files in SFDX source format: a source file with the actual content, and a sibling `<base>.<ext>-meta.xml` carrying deployment metadata. The JSON's `content` field (when present, base64-encoded) corresponds to the source file on disk:
-
-| Type | Source file | Meta sidecar |
-|---|---|---|
-| ApexClass | `MyClass.cls` (Apex code) | `MyClass.cls-meta.xml` |
-| ApexTrigger | `MyTrigger.trigger` (Apex code) | `MyTrigger.trigger-meta.xml` |
-| ApexComponent | `MyComp.component` (markup) | `MyComp.component-meta.xml` |
-| ApexPage | `MyPage.page` (Visualforce markup) | `MyPage.page-meta.xml` |
-| StaticResource | `MyResource.<ext>` (any payload) | `MyResource.resource-meta.xml` |
-| AuraDefinitionBundle | bundle dir with `.cmp`/`.app`/`.evt` + `.js` + `.css` etc. | `bundle-meta.xml` inside the dir |
-| LightningComponentBundle | bundle dir with `.html`/`.js`/`.css` | `bundle.js-meta.xml` inside the dir |
-
-When a JSON file contains a `content` field of type `base64`, that's the SOAP-API artifact equivalent of the disk source file. Authors write the source file directly; the `-meta.xml` sidecar carries fields like `apiVersion` and `status`.
-
-#### Child Metadata Types (legacy MDAPI vs SFDX source format)
-
-Some metadata types appear in the index but are **child elements** of a parent type, not standalone files. Examples: `ValidationRule`, `WebLink`, `RecordType`, `CompactLayout`, `ListView`, `BusinessProcess`, `FieldSet`, `SharingReason`, `Index` — all nested under `CustomObject`. Their JSON files lack `file_information` and `directory_location` because the legacy MDAPI form serializes them inline inside the parent `.object` file.
-
-In modern **SFDX source format**, these child types are decomposed into their own files under the parent object directory:
-
-```text
-force-app/main/default/objects/MyObject__c/
-├── MyObject__c.object-meta.xml
-├── fields/
-│   └── MyField__c.field-meta.xml
-├── validationRules/
-│   └── My_Rule.validationRule-meta.xml
-├── recordTypes/
-│   └── My_RT.recordType-meta.xml
-├── webLinks/
-│   └── My_Link.webLink-meta.xml
-├── compactLayouts/
-│   └── My_Layout.compactLayout-meta.xml
-└── listViews/
-    └── My_View.listView-meta.xml
-```
-
-The JSON's `declarative_metadata_sample_definition` shows the legacy inline form (e.g., `<validationRules>` inside `<CustomObject>`). When authoring in SFDX source format, take the inner element of that sample, drop it into its own file under the appropriate sub-directory, and add the standard `<?xml ...?>` + namespace wrapper using the type name as the root (e.g., `<ValidationRule xmlns=...>`).
-
-#### Directory Structure (Salesforce DX)
-
-```text
-force-app/main/default/
-├── objects/
-│   └── MyObject__c/
-│       ├── MyObject__c.object-meta.xml
-│       └── fields/
-│           └── MyField__c.field-meta.xml
-├── flows/
-│   └── My_Flow.flow-meta.xml
-├── classes/
-│   ├── MyClass.cls
-│   └── MyClass.cls-meta.xml
-└── profiles/
-    └── Admin.profile-meta.xml
-```
-
-### Examples of Well-Formed Files
-
-**CustomObject Example**:
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
-    <label>My Custom Object</label>
-    <pluralLabel>My Custom Objects</pluralLabel>
-    <nameField>
-        <label>Name</label>
-        <type>Text</type>
-    </nameField>
-    <deploymentStatus>Deployed</deploymentStatus>
-    <sharingModel>ReadWrite</sharingModel>
-    <enableActivities>true</enableActivities>
-    <enableHistory>true</enableHistory>
-</CustomObject>
-```
-
-**Flow Example**:
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<Flow xmlns="http://soap.sforce.com/2006/04/metadata">
-    <apiVersion>61.0</apiVersion>
-    <status>Active</status>
-    <processType>AutoLaunchedFlow</processType>
-    <start>
-        <locationX>50</locationX>
-        <locationY>50</locationY>
-    </start>
-</Flow>
-```
-## Updates & Versioning
-
-### Current Version
-
-- **API Version**: 67.0
-- **Release**: Summer 26
-- **Generated**: 2026-06-10 11:21:11
-
-### Version Compatibility
-
-This skill documentation is generated from Salesforce Metadata API version 67.0. When working with different API versions:
-
-- **Newer versions**: May have additional fields or metadata types not documented here
-- **Older versions**: Some fields or types may not be available
-- **Check your org**: Use `sf project retrieve` to see what's available in your org
-
-### Updating the Skill
-
-This skill is automatically generated from source JSON files. To update:
-
-1. Regenerate source JSON files from latest Salesforce WSDL
-2. Run the skill generator script
-3. Review changes in generation log
-4. Deploy updated skill
-## Additional Resources
-
-### Official Salesforce Documentation
-
-- [Metadata API Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/)
-- [Metadata Types Reference](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_types_list.htm)
-- [Salesforce DX Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/)
-
-### Salesforce CLI Commands
-
-- `sf project deploy validate`: Validate metadata before deploying
-- `sf project deploy start`: Deploy metadata to org
-- `sf project retrieve start`: Retrieve metadata from org
-- `sf project convert`: Convert between source and metadata formats
-
-### Related Skills
-
-- **Enterprise API**: For SOQL queries and DML operations
-- **Tooling API**: For development tools and metadata queries
-- **SFDX**: For project structure and deployment
-## Support
-
-### Getting Help
-
-If you encounter issues or have questions:
-
-1. **Check the Index**: `metadata_index_table.md` (in this `references/` folder) lists all available types
-2. **Review Examples**: See usage examples above for common patterns
-3. **Consult WSDL**: Check `wsdl_segment` in JSON files for schema details
-4. **Salesforce Documentation**: Official docs have additional context
-
-### Reporting Issues
-
-For issues with this skill:
-
-- Check that the metadata type exists in your Salesforce org version
-- Verify file paths are correct
-- Review generation log for warnings or errors
-- Contact the skill maintainer with specific error details
-
-### Contributing
-
-This skill is automatically generated. To contribute:
-
-- Report incorrect or missing information
-- Suggest improvements to documentation structure
-- Provide feedback on token optimization strategies
-
----

package/skills/handling-sf-data/CREDITS.md

@@ -1,5 +0,0 @@
-# Credits & Acknowledgments
-
-This skill is built on established Salesforce data, SOQL, and bulk operation patterns from the Salesforce platform ecosystem.
-
----

package/skills/handling-sf-data/README.md

@@ -1,112 +0,0 @@
-# handling-sf-data
-
-Salesforce data operations skill for Claude Code. Create, validate, bulk-load, clean up, and troubleshoot org data with a describe-first workflow.
-
-## Features
-
-- **CRUD Operations**: Create, read, update, delete records via sf CLI
-- **Describe-First Validation**: Inspect required fields, picklists, and createable fields before data creation
-- **CLI-First Test Data**: Prefer `sf data` commands for straightforward seed data
-- **Bulk Operations**: Import/export via Bulk API 2.0
-- **Record Tracking & Cleanup**: Savepoint/rollback, cleanup scripts, delete-by-pattern workflows
-- **130-Point Validation**: Automated scoring across 7 categories
-
-## Installation
-
-Add the skill to your Cursor project by placing the `handling-sf-data` directory under your `skills/` folder and enabling it in your agent configuration.
-
-## Usage
-
-Invoke the skill:
-```
-Skill(skill="handling-sf-data")
-Request: "Create 251 test Account records with varying Industries for trigger testing in org dev"
-```
-
-### Common Operations
-
-| Operation | Example Request |
-|-----------|-----------------|
-| Query | "Query all Accounts with related Contacts in org dev" |
-| Create | "Create 10 test Opportunities at various stages" |
-| Bulk Insert | "Insert 500 accounts from accounts.csv" |
-| Update | "Update Account 001xxx with new Industry" |
-| Delete | "Delete all test records with Name LIKE 'Test%'" |
-| Cleanup | "Generate cleanup script for all records created today" |
-
-## Recommended workflow
-
-1. Describe the target object when schema constraints are uncertain
-2. Validate required fields, picklist values, and createable fields
-3. Choose CLI, tree import, bulk import, or anonymous Apex intentionally
-4. Verify results and provide cleanup instructions
-
-## Validation Scoring (130 Points)
-
-| Category | Points | Focus |
-|----------|--------|-------|
-| Query Efficiency | 25 | SOQL selectivity, indexed fields, no N+1 |
-| Bulk Safety | 25 | Governor limits, batch sizing |
-| Data Integrity | 20 | Required fields, relationships |
-| Security & FLS | 20 | Field-level security, no PII |
-| Test Patterns | 15 | 200+ records, edge cases |
-| Cleanup & Isolation | 15 | Rollback, cleanup scripts |
-| Documentation | 10 | Purpose, expected outcomes |
-
-## Cross-Skill Integration
-
-### With deploying-metadata
-```
-Skill(skill="deploying-metadata")
-Request: "Describe Invoice__c in org dev - show all fields"
-```
-Then use handling-sf-data with accurate field names and permitted values.
-
-### From generating-apex / generating-flow
-```
-Skill(skill="handling-sf-data")
-Request: "Create 251 test Accounts to trigger AccountTrigger bulk testing"
-```
-
-## Directory Structure
-
-```
-handling-sf-data/
-├── SKILL.md                   # Main skill prompt
-├── assets/
-│   ├── factories/             # Apex test data factories
-│   ├── soql/                  # SOQL query templates
-│   ├── bulk/                  # Bulk operation templates
-│   ├── csv/                   # CSV import templates
-│   ├── json/                  # JSON tree templates
-│   └── cleanup/               # Cleanup scripts
-├── scripts/                   # Pre-flight validation scripts
-└── references/                # Documentation and examples
-```
-
-## Key documentation
-
-- [SKILL.md](SKILL.md) - Full workflow and orchestration guidance
-- [references/test-data-best-practices.md](references/test-data-best-practices.md) - Describe-first validation and retry strategy
-- [references/sf-cli-data-commands.md](references/sf-cli-data-commands.md) - sf CLI command patterns
-- [references/cleanup-rollback-guide.md](references/cleanup-rollback-guide.md) - Cleanup strategies
-
-## sf CLI Commands Wrapped
-
-| Operation | Command |
-|-----------|---------|
-| Query | `sf data query --query "..." --target-org [alias]` |
-| Create | `sf data create record --sobject [Object] --values "..."` |
-| Update | `sf data update record --sobject [Object] --record-id [Id] --values "..."` |
-| Delete | `sf data delete record --sobject [Object] --record-id [Id]` |
-| Bulk Import | `sf data import bulk --file [csv] --sobject [Object]` |
-| Bulk Delete | `sf data delete bulk --file [csv] --sobject [Object]` |
-| Tree Export | `sf data export tree --query "..." --output-dir [dir]` |
-| Tree Import | `sf data import tree --files [json]` |
-| Apex Run | `sf apex run --file [script.apex]` |
-
-## Requirements
-
-- sf CLI v2
-- Target Salesforce org (sandbox or production)
-- Claude Code with skill plugins enabled