Add enriching-metadata-business-context skill

2026-08-03 05:41:08 +08:00 · 2026-05-13 21:43:31 -07:00 · 2026-05-13 21:43:31 -07:00 · 46e82658bf
commit 46e82658bf
parent 3253e248a9
1 changed files with 295 additions and 0 deletions
--- a/skills/enriching-metadata-business-context/SKILL.md
+++ b/skills/enriching-metadata-business-context/SKILL.md
@ -0,0 +1,295 @@
+# Skill: Enriching Metadata Business Context
+
+## Trigger Conditions
+MUST activate whenever the agent is creating, generating, or editing any Salesforce metadata source file whose path matches `force-app/**/*-meta.xml` (e.g. CustomObject, CustomField, Apex class, LWC, Flow, etc.).
+
+**Supported Metadata Types (initially):**
+- Custom Objects (`*__c.object-meta.xml`)
+- Lightning Web Components (`lwc/**/*.js-meta.xml`)
+
+## Objective
+Ensure the entity's `<enrichments>` block (for org-fetched metadata) or new `<ai>` block (for locally-created metadata) contains an `<enrichedDescription>` with business context explaining WHY it was created, HOW the decision was made, and WHAT it does.
+
+**Content Requirements:**
+- Maximum 50 words
+- Three aspects: WHY created, HOW decision made, WHAT it does
+- Plain text only - no special formatting, no XML tags within description
+- Single continuous paragraph (no separate sections/tags)
+
+## XML Structure Requirements
+
+### For Locally-Created Metadata (New)
+The `<ai>` tag MUST be inserted as a direct child of the root metadata element (e.g., `<CustomObject>`, `<LightningComponentBundle>`) and positioned before the closing tag:
+
+```xml
+<ai>
+    <enrichedDescription>Plain text description combining WHY, HOW, and WHAT in 50 words or less</enrichedDescription>
+</ai>
+```
+
+### For Org-Fetched Metadata (Already has `<enrichments>`)
+When metadata is fetched from org, it may contain:
+
+```xml
+<enrichments>
+    <aiDescriptor>
+        <accuracyScore>0.95</accuracyScore>
+        <enrichedDescription>Existing description from Salesforce</enrichedDescription>
+        <skipEnrichment>false</skipEnrichment>
+    </aiDescriptor>
+</enrichments>
+```
+
+**DO NOT** create a new `<ai>` tag. Instead, append context to the existing `<enrichedDescription>` within `<enrichments>`.
+**DO NOT** touch `<accuracyScore>` or `<skipEnrichment>` tags - they are generated by Salesforce.
+
+## Content Generation Guidelines
+
+Generate a single, concise paragraph (maximum 50 words) that addresses:
+
+1. **WHY** - Why was this created? What business problem or opportunity does it address?
+2. **HOW** - How was the decision made? What factors influenced the design?
+3. **WHAT** - What does this entity do? What is its primary purpose and functionality?
+
+**Format:**
+- Single continuous paragraph
+- No XML tags within the description
+- No special formatting (no bold, italics, bullets)
+- Plain text only
+- Maximum 50 words
+- Use present tense
+- Escape XML special characters: `&` → `&`, `<` → `<`, `>` → `>`, `'` → `'`, `"` → `"`
+
+**Example (Custom Object):**
+```
+Manages customer orders across sales channels to enable revenue tracking and fulfillment. Created to centralize order data from multiple systems and support automated order processing workflows. Tracks order details, status, line items, and integrates with inventory and shipping systems.
+```
+
+**Example (LWC):**
+```
+Displays real-time product inventory levels on order entry screens to prevent overselling. Designed to replace manual inventory checks and improve order accuracy. Fetches stock data via GraphQL and updates dynamically as orders are placed.
+```
+
+## Workflow Instructions
+
+### Step 1: Detect Metadata Source and State
+Determine the scenario:
+
+**Scenario 1: Fetched from Org (has `<enrichments>` tag)**
+- Action: Append new context to existing `<enrichedDescription>` within `<enrichments>`
+- Do NOT create new `<ai>` tag
+- Do NOT modify `<accuracyScore>` or `<skipEnrichment>`
+
+**Scenario 2: Locally Created (no `<enrichments>` or `<ai>` tag)**
+- Action: Create new `<ai>` tag with `<enrichedDescription>`
+- Insert before closing root element tag
+
+**Scenario 3: Locally Edited (has `<ai>` tag)**
+- Action: Update existing `<enrichedDescription>` within `<ai>` tag
+- Replace entire description with new context
+
+**Scenario 4: Org-Fetched then Locally Edited (has `<enrichments>` tag)**
+- Action: Append new context to existing `<enrichedDescription>` within `<enrichments>`
+- Keep org-generated tags (`<accuracyScore>`, `<skipEnrichment>`) unchanged
+
+### Step 2: Gather Context
+Collect information to generate description:
+- User's stated purpose and requirements
+- Field definitions (for objects)
+- Component functionality (for LWC)
+- Relationships and integrations
+- Business process it supports
+- Stakeholders who will use it
+
+### Step 3: Generate Description
+Create a single 50-word paragraph that combines:
+1. WHY - Business justification
+2. HOW - Decision-making factors
+3. WHAT - Functional purpose
+
+**Rules:**
+- Maximum 50 words
+- Plain text only
+- No XML tags in content
+- Escape special characters properly
+- Use present tense
+- Be specific, not generic
+
+### Step 4: Insert or Update Description
+
+**For Locally-Created (New `<ai>` tag):**
+```xml
+<ai>
+    <enrichedDescription>Your generated 50-word description here</enrichedDescription>
+</ai>
+```
+
+**For Org-Fetched or Org-Fetched-Then-Edited (Update `<enrichments>`):**
+```xml
+<enrichments>
+    <aiDescriptor>
+        <accuracyScore>0.95</accuracyScore>
+        <enrichedDescription>Original description. [Appended new context here]</enrichedDescription>
+        <skipEnrichment>false</skipEnrichment>
+    </aiDescriptor>
+</enrichments>
+```
+
+**For Locally-Edited (Update existing `<ai>`):**
+Replace the entire `<enrichedDescription>` content with newly generated description.
+
+### Step 5: Validate
+Ensure:
+- Well-formed XML
+- Proper character escaping
+- Description ≤ 50 words
+- Tag placement correct
+- Org-generated tags preserved (if applicable)
+
+## Critical Rules
+
+### 1. Detect Source Correctly
+**Check for `<enrichments>` tag first:**
+- If present → Metadata was fetched from org
+- If absent → Metadata was created locally
+
+### 2. Handle Org-Generated Tags
+When `<enrichments>` exists:
+- ✅ Append to `<enrichedDescription>`
+- ❌ Do NOT create new `<ai>` tag
+- ❌ Do NOT modify `<accuracyScore>`
+- ❌ Do NOT modify `<skipEnrichment>`
+- ❌ Do NOT remove any existing tags
+
+### 3. Content Constraints
+- **Maximum 50 words** - strictly enforced
+- **Plain text only** - no XML tags, no formatting
+- **Escape XML characters** - `&`, `<`, `>`, `'`, `"`
+- **Single paragraph** - no line breaks for separate WHY/HOW/WHAT sections
+
+### 4. Metadata Type Support
+**Currently Supported:**
+- Custom Objects (`*__c.object-meta.xml`)
+- Lightning Web Components (`lwc/**/*.js-meta.xml`)
+
+**Not Supported (yet):**
+- Custom Fields, Flows, Apex classes, etc.
+
+### 5. Deployment Safety
+- `<ai>` tags are custom extensions
+- ✅ Preserved in source control
+- ✅ Deploy without errors (Salesforce ignores unknown tags)
+- ⚠️ Not visible in Salesforce UI
+- ⚠️ Documentation only, no runtime effect
+
+## Example Outputs
+
+### Example 1: Locally-Created Custom Object
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
+    <label>Product</label>
+    <nameField>
+        <label>Product Name</label>
+        <type>Text</type>
+    </nameField>
+    <deploymentStatus>Deployed</deploymentStatus>
+    <sharingModel>ReadWrite</sharingModel>
+    <visibility>Public</visibility>
+    <ai>
+        <enrichedDescription>Manages customer orders across sales channels to enable revenue tracking and fulfillment. Created to centralize order data from multiple systems and support automated order processing workflows. Tracks order details, status, line items, and integrates with inventory systems.</enrichedDescription>
+    </ai>
+</CustomObject>
+```
+
+### Example 2: Org-Fetched Custom Object (with enrichments)
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
+    <label>Product</label>
+    <deploymentStatus>Deployed</deploymentStatus>
+    <enrichments>
+        <aiDescriptor>
+            <accuracyScore>0.95</accuracyScore>
+            <enrichedDescription>Maintains the organization's product catalog with detailed information about items available for sale. Additional context: Enables sales team to track pricing, inventory levels, and product specifications for accurate quoting and order fulfillment processes.</enrichedDescription>
+            <skipEnrichment>false</skipEnrichment>
+        </aiDescriptor>
+    </enrichments>
+    <sharingModel>ReadWrite</sharingModel>
+    <visibility>Public</visibility>
+</CustomObject>
+```
+
+### Example 3: Locally-Created LWC
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>59.0</apiVersion>
+    <isExposed>true</isExposed>
+    <targets>
+        <target>lightning__RecordPage</target>
+    </targets>
+    <ai>
+        <enrichedDescription>Displays real-time product inventory levels on order entry screens to prevent overselling. Designed to replace manual inventory checks and improve order accuracy. Fetches stock data via GraphQL and updates dynamically as orders are placed.</enrichedDescription>
+    </ai>
+</LightningComponentBundle>
+```
+
+## Anti-Patterns to Avoid
+
+| Don't | Why | Do Instead |
+|-------|-----|------------|
+| Create `<ai>` when `<enrichments>` exists | Breaks the org-fetched pattern | Append to existing `<enrichedDescription>` |
+| Exceed 50 words | Violates requirement | Keep concise, edit ruthlessly |
+| Use XML formatting in description | Breaks XML structure | Plain text only |
+| Modify `<accuracyScore>` or `<skipEnrichment>` | These are org-generated | Leave them untouched |
+| Generic descriptions like "stores data" | Lacks business context | Explain WHY, HOW, WHAT specifically |
+| Create new `<ai>` for every edit | Clutters metadata | Update existing description |
+
+## Success Criteria
+
+After applying this skill, verify:
+- [ ] Correct tag used (`<ai>` for local, update `<enrichments>` for org-fetched)
+- [ ] `<enrichedDescription>` contains WHY, HOW, WHAT in ≤50 words
+- [ ] Plain text only, no XML tags within description
+- [ ] Special characters properly escaped
+- [ ] Org-generated tags (`<accuracyScore>`, `<skipEnrichment>`) preserved if present
+- [ ] XML is well-formed and valid
+- [ ] Tag placement doesn't interfere with Salesforce deployment
+
+## Notes for A4v Agent
+
+When this skill is active:
+
+### Critical First Step
+**Always check for `<enrichments>` tag FIRST:**
+```
+IF <enrichments> exists:
+    → Scenario 1 or 4: Append to <enrichedDescription> within <enrichments>
+ELSE IF <ai> exists:
+    → Scenario 3: Update <enrichedDescription> within <ai>
+ELSE:
+    → Scenario 2: Create new <ai> tag with <enrichedDescription>
+```
+
+### Content Generation
+1. **Ask for business context** if not provided in the request
+2. **Gather WHY, HOW, WHAT** from user requirements and existing metadata
+3. **Write in present tense** ("manages", "tracks", "enables")
+4. **Be specific** - reference actual fields, processes, stakeholders
+5. **Count words** - maximum 50 words strictly enforced
+6. **Plain text only** - no bold, italics, bullets, or XML tags
+
+### Appending to Org-Fetched Metadata
+When appending to existing `<enrichedDescription>`:
+- Add a space, then "Additional context: [your description]"
+- Or use a period and start new sentence: ". [Your description]"
+- Preserve all original content
+- Ensure combined text still makes sense
+
+### Quality Checks
+- Description addresses WHY, HOW, and WHAT
+- ≤50 words total
+- No special characters unescaped
+- Specific to this metadata entity
+- Makes sense to a developer reading it later