@salesforce/afv-skills 1.55.0 → 1.57.0

package/skills/sales-call-scoring-configure/SKILL.md

@@ -0,0 +1,318 @@
+---
+name: sales-call-scoring-configure
+description: "Configure, set up, or repair AI Call Scoring (a.k.a. Call Coaching / Coaching Competencies) on an ECI-enabled Salesforce org. Flips ECICallScoringEnabled via SOAP Metadata API, enables Einstein Generative AI Platform if off, and manages Coaching Competency records (EnablementCompetencyDef Tooling API): install the 6 OOTB set, the 7 Momentum best-practice prompts, or conversationally author/edit/activate/deactivate custom competencies (8-active + 16000/255-char caps). TRIGGER when: user wants to turn on AI Call Scoring or Call Coaching, install OOTB or best-practice competencies, create/edit custom competencies, re-enable after sandbox refresh, or verify/repair partial Call Coaching setup on a 68+ ECI org. DO NOT TRIGGER when: no ECI license (direct to Agentforce for Sales), user wants to enable ECI/Momentum themselves (out of scope — Setup), Pipeline Management (use sales-agentforce-pipeline-management-configure), or custom agent (use agentforce-generate)."
+metadata:
+  version: "1.0"
+  domains: ["Sales"]
+  minApiVersion: "68.0"
+  relatedSkills:
+    - "sales-agentforce-pipeline-management-configure"
+    - "agentforce-generate"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+    - tool: ["jq"]
+      semver: ">=1.6.0"
+    - tool: ["curl"]
+      semver: ">=7.0.0"
+  accessCheck:
+    - type: "orgPref"
+      value: "ConversationPilotPref"
+    - type: "userPerm"
+      value: "ModifyAllData"
+---
+
+# Sales Call Scoring — Configure
+
+Configure **Call Coaching** (a.k.a. AI Call Scoring / Coaching Competencies)
+on a Salesforce org. Detects the org's current state, enables dependent
+features it is authorized to enable, and flips the `ECICallScoringEnabled`
+org preference via the SOAP Metadata API.
+
+## Scope
+
+**In scope**
+- **ECI-enabled orgs only.** The skill supports orgs on the ECI (Einstein
+  Conversation Insights) arm (spike scope: ECI-only for MVP).
+- Detect which of the 4 PRD-scoped org states the org is in.
+- Enable **Einstein Generative AI Platform** if off (PRD-authorized dependency).
+- Flip `enableECICallScoring` to `true` via SOAP Metadata API v68.
+- Verify the change took effect.
+- Idempotent — clean exit on states 3 and 4 (already enabled).
+
+**Out of scope**
+- **River Rush / Momentum detection.** Deferred until that arm goes live —
+  see Key Considerations. A Momentum-only org today is not distinguished
+  from any other ECI-off org; it gets the generic "ECI is not enabled"
+  message from Phase 3, not a Momentum-specific one.
+- **Enabling ECI or Momentum themselves.** PRD-explicit out-of-scope; the skill
+  detects and messages the admin to enable ECI via Setup.
+- **License provisioning.** Missing base licenses (Agentforce for Sales, ECI
+  license) require an account-team ticket.
+- **Competency CRUD.** Handled by sibling scripts in this same skill — see "Competency CRUD workflow" below (§S3-§S10) and the "Execution sequence" matrix.
+
+## Prerequisites
+
+1. **`sf` CLI authenticated** — `sf org login web --alias <org-alias>`.
+2. ECI arm licensed and enabled: `ConversationPilot` org permission (Phase 0
+   purchase gate) and `enableCallCoaching` pref (Phase 1, the
+   `ConversationPilotPref` preference). (River Rush/Momentum is a separate
+   arm covered by the same server-side gate but not checked by this skill
+   yet — see Key Considerations.)
+3. Site gate `com.salesforce.eci.callScoringEnabled` open on the org's pod
+   (RelEng-controlled; not admin-toggleable).
+
+Einstein GenAI Platform is a soft prerequisite — the skill enables it
+automatically when off.
+
+## Clarifying Questions
+
+Ask the admin: target org alias? Sandbox refresh scenario? (The pref has
+`disableOnSandboxCopy=true`, so it must be re-flipped after every refresh —
+that's normal, not a failure.)
+
+## Admin Communication Guidelines
+
+**CRITICAL**: This skill serves admin users, not developers. The full 13-rule spec with rationale for each rule lives in [`references/admin-communication.md`](references/admin-communication.md) — consult it before your first response in this skill. Summary of the load-bearing rules:
+
+1. **Run all bash commands in background** (`run_in_background: true`).
+2. **Speak admin language, not entity language** — "Call Coaching", "Coaching Competency", "active/inactive". Never `EnablementCompetencyDef`, `enableECICallScoring`, `EvaluationInstructions`, `SourceCompetencyTemplate` in primary chat text.
+3. **Hide technical details** — no record Ids, DeveloperNames, Template enum keys, HTTP codes, SOAP responses, curl/jq internals, script paths, or phase numbers. Exception: the S9 verify markdown table (see [`references/competency-crud.md`](references/competency-crud.md) §S9).
+4. **Chain automatically** — when a script prints `Next: <script>`, run it in the same turn without asking. **Exception**: State 3 → rule #13.
+5. **Ask OOTB-vs-custom once** — on first-time competency setup (State 3, unqualified intent), render `install-ootb-competencies.sh --list` and let the admin choose. Only checkpoint in this skill where Claude asks before writing.
+6. **Idempotency is silent** — if already on/installed, say so briefly and move on.
+
+See [`references/admin-communication.md`](references/admin-communication.md) for the full 13-rule spec, including error-surfacing, outcome-vs-steps reporting, and the S9 carve-out rationale.
+
+## Workflow
+
+### Phase 0 — Auth
+
+Resolves org auth via the shared `scripts/shared/auth.sh` helper
+(`resolve_org_auth "$ORG_ALIAS"`), which every script in this skill sources:
+validate the alias format, call `sf org display` for `instanceUrl` and
+`accessToken` (falling back to `sf org auth show-access-token` when the CLI
+redacts the token), refuse a non-HTTPS instance URL, and fail closed with an
+explicit `sf org login web --alias <alias>` instruction if the org isn't
+reachable or no token can be extracted. If `ACCESS_TOKEN`/`INSTANCE_URL` are
+already exported for the same alias — e.g. a parent shell already resolved
+auth and is chaining multiple of these scripts in one session — resolution
+is skipped and the cached values are reused. `orgId` is not part of this
+helper; `enable-call-scoring.sh` fetches it separately (via its own
+`sf org display`) purely for the status banner.
+
+### Phase 0 — ECI purchase gate
+
+Before any state detection, query the `ConversationPilot` OrgPermission via
+Tooling API (`OrganizationSettingsDetail`, same pattern as the
+`ECICallScoringAI` gate in Phase 3). This is a license/purchase check,
+distinct from `enableCallCoaching` below (the admin's Setup toggle for an
+org that's already licensed):
+
+- **Not enabled:** exit with: "Call Coaching couldn't be turned on because
+  this org doesn't have Einstein Conversation Insights, which is required
+  to use Call Coaching. To proceed, an admin can go to Setup → Salesforce Go
+  → Einstein Conversation Insights, or contact their sales representative,
+  to understand how to purchase ECI." Non-zero exit.
+- **Enabled:** proceed to Phase 1's `enableCallCoaching` check.
+
+### Phase 1 — State detection
+
+SOAP `readMetadata` at `/services/Soap/m/68.0` against two settings types:
+
+1. `ConversationalIntelligenceSettings` → read `enableCallCoaching` (ECI arm)
+   and `enableECICallScoring` (current Call Coaching state).
+2. `EinsteinGptSettings` → read `enableEinsteinGptPlatform`.
+
+(`RiverRushSettings`/`riverRushEnabled` — Momentum — is NOT read. That
+detection is deferred until the River Rush arm goes live; see Key
+Considerations for where to re-add it.)
+
+Query existing competencies via Tooling API:
+`SELECT COUNT() FROM EnablementCompetencyDef`.
+
+Classify the org into one of 4 states:
+
+| State | Detection |
+|---|---|
+| 1a. Not available (no ECI license) | Cannot read `ConversationalIntelligenceSettings` |
+| 2. Available, not enabled | `enableCallCoaching=true` AND `enableECICallScoring=false` |
+| 3. Enabled, no competencies | `enableECICallScoring=true` AND count = 0 |
+| 4. Enabled, with competencies | `enableECICallScoring=true` AND count > 0 |
+
+### Phase 2 — Route by state
+
+- **State 1a:** Exit with PRD-verbatim message: "AI call coaching is not
+  available in this org and they need Agentforce for Sales." Non-zero exit.
+- **State 3 / State 4:** Exit 0 with a ready-for-competency-setup message.
+- **State 2:** Proceed.
+
+### Phase 3 — Prerequisite enablement (State 2 only)
+
+- **License gate (checked first):** query `OrganizationSettingsDetail`
+  (Tooling API) for the `ECICallScoringAI` OrgPermission. If it isn't
+  `true`, exit with: "AI call coaching is not available in this org and org
+  requires Agentforce for Sales license." Non-zero exit. This runs even
+  when `enableCallCoaching`/`enableECICallScoring` already read favorably,
+  since those settings don't by themselves confirm the org is licensed.
+  **Must run before the ECI-off check below** — a genuinely unlicensed org
+  and a licensed-but-toggled-off org both read `enableCallCoaching=false`,
+  so checking ECI first would misdiagnose a licensing gap as a self-serve
+  Setup toggle (the regression the `NoLicense` eval dataset guards against).
+- If **ECI is off**: refuse with a Setup pointer, exit non-zero. This skill
+  does NOT enable ECI (PRD explicit). (A Momentum-only org lands here too,
+  since Momentum isn't detected separately — it gets this same generic
+  message, not a Momentum-specific one.)
+- If **Einstein GenAI off**: SOAP `updateMetadata` on `EinsteinGptSettings`
+  with `enableEinsteinGptPlatform=true`. PRD explicitly authorizes this. If
+  it's already on, skip the `updateMetadata` call and tell the admin it's
+  already enabled. If the update fails because the org isn't licensed for
+  `EinsteinGptSettings` (or is explicitly refused with no fault): tell the
+  admin they need **Agentforce for Sales** to enable AI Call Scoring, and
+  that without it they can still set up **manual call scoring** via
+  Salesforce Go setup. A distinct auth/permission or network/timeout failure
+  gets its own message (check CLI session / retry) rather than the licensing
+  message, since those aren't licensing gaps.
+
+### Phase 4 — Enable Call Coaching (State 2 only)
+
+If `enableECICallScoring` already reads `true` (e.g. it changed out-of-band
+between Phase 1's read and here), skip the update and tell the admin it's
+already enabled. Otherwise SOAP `updateMetadata` on
+`ConversationalIntelligenceSettings` with `enableECICallScoring=true`.
+Require `<success>true</success>`.
+
+### Phase 5 — Verify (State 2 only)
+
+Re-read `enableECICallScoring`. Require `true`. Print SOAP response on failure.
+
+## Key Considerations
+
+- **API version is v68.0**, not v64.0. `enableECICallScoring` is not
+  present in the `ConversationalIntelligenceSettings` schema at lower API
+  versions on some builds — v68 is the safe minimum. The Pipeline skill uses
+  v64 because its target field (`SalesDealAgentSettings.enableDealAgent`) is
+  present there; Call Scoring is not.
+- **Do NOT use `sf mdapi deploy`** for this pref. It has a silent failure
+  mode where the CLI reports success but the pref doesn't flip. Use raw
+  SOAP `updateMetadata` — the response's `<success>` boolean is authoritative.
+- **The server-side gate is broader than this skill's scope.** The
+  `orgHasCallScoring` access check allows the ECI arm OR the River Rush
+  (Momentum) arm — see `CoachingCompetenciesFeature.isFeatureAvailableInOrg()`.
+  This skill deliberately narrows to the ECI arm (MVP scope per the spike).
+- **River Rush (Momentum) detection is deliberately absent right now**, not
+  an oversight — the arm isn't live yet. `enable-call-scoring.sh` used to
+  read `RiverRushSettings.riverRushEnabled` and refuse Momentum-only orgs
+  with a distinct "State 1b" message / emit a Momentum-available-but-off
+  advisory; both were removed. Re-add them (the read, the State 1b branch,
+  and the Phase 3 advisory) once River Rush ships — the removed code is
+  recoverable from git history on this file.
+- **`disableOnSandboxCopy=true`** — every sandbox refresh disables this pref.
+  Admins re-running the skill after a refresh is the expected pattern; the
+  idempotency check makes that safe.
+- **Site switch** `com.salesforce.eci.callScoringEnabled` must be open on
+  the org's pod. It's not admin-toggleable and not readable via SOAP. If
+  closed, `updateMetadata` returns a well-formed response with
+  `<success>false</success>` and an `<errors><statusCode>…</statusCode></errors>`
+  block — it does NOT emit a SOAP `<Fault>`. `parse_soap_response` extracts
+  the statusCode and surfaces it via the `WRITE_ERROR:…` classification.
+- **ECI provisioning is asynchronous.** For a short window after
+  `enableCallCoaching` flips on, the dependent `enableECICallScoring` field
+  is server-side read-only and `updateMetadata` returns
+  `INSUFFICIENT_ACCESS_OR_READONLY`. `enable-call-scoring.sh` maps this to a
+  transient "still finishing turning on — wait a few minutes and re-run"
+  message rather than a terminal failure (W-23968462).
+- **Every SOAP call is bounded by a 30s timeout** (`CURL_TIMEOUT` in
+  `enable-call-scoring.sh`, matching the only existing timeout precedent in
+  this repo — the Pipeline skill's `setup-all.sh`) and classified via
+  `shared/soap.sh`'s `parse_soap_response` into `true` / `false` /
+  `AUTH_ERROR:...` / `TYPE_UNAVAILABLE:...` / `WRITE_ERROR:…` /
+  `NETWORK_ERROR`. This distinguishes "org isn't licensed for this setting"
+  from "auth/permission fault" from "server refused the write with a specific
+  statusCode" from "network/timeout error" — instead of collapsing them into
+  an empty string or dumping raw SOAP XML at the admin.
+- **`enable-call-scoring.sh` uses raw SOAP, not `sf api request rest`.**
+  Every other script in this skill uses `sf api request rest` so the CLI
+  manages auth end-to-end. `enable-call-scoring.sh` is the sole exception:
+  it calls the SOAP Metadata API (`readMetadata`/`updateMetadata`) directly,
+  because no non-beta Salesforce CLI command exposes SOAP Metadata reads/
+  writes for `ConversationalIntelligenceSettings` et al., and `sf mdapi
+  deploy` has the silent-failure mode noted above for this exact field. This
+  is a deliberate, scoped exception, not an oversight.
+
+## References
+
+- **Reference skill** (canonical single-OrgPref pattern):
+  `skills/sales-agentforce-pipeline-management-configure/`
+- **SOAP helpers**: `scripts/shared/soap.sh` (copied from the Pipeline skill —
+  `redact_token`, `parse_soap_response`)
+- **Server-side gate** (declarative access check):
+  `core/conversation-udd/java/resources/udd/conversation-udd/ConversationalIntelligence.accessChecks.xml`
+  — `orgHasCallScoring` = ECI arm OR River Rush arm; `orgHasECICallScoringWithAI`
+  adds Einstein GenAI + `ECICallScoringAI` license perm on top.
+- **Pref declaration**:
+  `core/conversation-udd/java/resources/udd/conversation-udd/ConversationalIntelligence.settings.xml`
+  — `<orgPreference name="ECICallScoringEnabled" mdApiName="enableECICallScoring" ...>`
+- **Java feature registration** (would be the entry point if a
+  SetupDiscoveryService REST/MCP wrapper existed): `core/conversation-impl/java/src/conversation/features/CoachingCompetenciesFeature.java`
+
+## Competency CRUD workflow
+
+Once Phase 5 confirms Call Coaching is enabled (or Phase 1 detects State 3/4), Claude runs the `Next:` script directly, in the same turn. Records are managed via Tooling API on `EnablementCompetencyDef` (setup entity, keyPrefix `1nA`, module `conversation-udd`). Cap: **8 simultaneously active** per org (`CoachingCompetenciesFeature.MAX_ACTIVE_COMPETENCIES`).
+
+All scripts share `shared/auth.sh` / `resolve_org_auth` — token propagates across chained invocations, no re-auth. Tooling API writes go through `sf api request rest` where practical; a subset (custom-CRUD variants, best-practice installer) drops to raw `curl` for finer request shape.
+
+Scripts fall into **two parallel families**:
+
+- **Generic** — `{create,edit,toggle,get}-competency.sh` — works on any competency.
+- **Custom-CRUD variants** — `*-custom-competency.sh` — harden the write path with SpecificCallsOnly filter JSON and richer validation.
+
+Prefer custom variants when the admin's intent is unambiguously custom (S5-created); fall back to generic on OOTB or unknown-provenance records.
+
+**Full spec** — S3 through S10 script contracts, S5's Q1-Q4 conversational drafting sequence, the admin-intent × org-state execution matrix, and chaining checkpoints — is in [`references/competency-crud.md`](references/competency-crud.md). Consult it whenever the admin's ask touches competency records (list, install, create/edit, activate, verify, delete).
+
+## Standalone Scripts (summary)
+
+| Script | Purpose |
+|---|---|
+| `enable-call-scoring.sh <alias>` | Detect state, enable Einstein GenAI if off, flip the Call Coaching pref (Phase 0-5). |
+| `list-competencies.sh <alias> [--verbose\|--json]` | List all competencies + status. Admin-safe by default; `--verbose` adds Ids/DeveloperNames; `--json` for the calling agent only. |
+| `install-ootb-competencies.sh <alias> [--dry-run]` | Install the 6 PRD-canonical OOTB competencies. |
+| `install-best-practice-competencies.sh <alias> [--dry-run] [--only "Name1,Name2"]` | Install the 7 Momentum best-practice reference prompts. `--only` filters by `MasterLabel`. |
+| `create-competency.sh <alias> <payload.json>` | Create one competency (generic — usable on OOTB or custom). |
+| `create-custom-competency.sh <alias> <payload.json>` | Create one custom competency (hardened variant — prefer for S5). |
+| `edit-competency.sh <alias> <ident> ...` | Edit description / instructions (generic). |
+| `edit-custom-competency.sh <alias> <ident> ...` | Edit description / instructions (custom-CRUD variant). |
+| `toggle-competency.sh <alias> <ident> <activate\|deactivate>` | Activate / deactivate (generic). |
+| `toggle-custom-competency.sh <alias> <ident> <activate\|deactivate>` | Activate / deactivate (custom-CRUD variant). |
+| `get-competency.sh <alias> <ident> [--field <f>]` | Fetch a record or single field (generic). |
+| `get-custom-competency.sh <alias> <ident> [--field <f>]` | Fetch a record or single field (custom-CRUD variant). |
+| `verify-ootb-competencies.sh <alias> ["Name" ...]` | Confirm expected competencies exist and are active — outputs the S9 admin-visible markdown table. |
+| _no delete script (yet)_ | Use `sf data delete record --sobject EnablementCompetencyDef --record-id <Id> --use-tooling-api` — see §S10. |
+
+## Admin Verification
+
+After a successful run, the admin can independently verify:
+
+**Via UI** — Salesforce Go → Coaching Competencies should now be reachable
+and show the feature as enabled with the configured competencies.
+
+**Via CLI** — two Tooling API queries:
+
+```bash
+# Feature enabled?
+sf data query --target-org <alias> --use-tooling-api \
+  --query "SELECT IsEciCallScoringEnabled FROM ConversationalIntelligenceSettings"
+
+# Competencies configured?
+sf data query --target-org <alias> --use-tooling-api \
+  --query "SELECT MasterLabel, IsActive, SourceCompetencyTemplate FROM EnablementCompetencyDef ORDER BY MasterLabel"
+```
+
+## Assets
+
+- `assets/ootb-competencies.json` — 6 PRD-canonical OOTB prompt bodies
+  (installed by `install-ootb-competencies.sh`).
+- `assets/best-practice-competencies.json` — 7 Momentum best-practice
+  prompt bodies (S5 authoring reference; also installable via
+  `create-competency.sh`).

package/skills/sales-call-scoring-configure/assets/best-practice-competencies.json

@@ -0,0 +1,67 @@
+{
+  "_meta": {
+    "source": "PRD 'Call Coaching Codey configure skill', section 'Momentum best practice agent instructions shared with customers' (Google Doc 1XKEDq9ig4du14qWOMv33mHcpBjF-bBwkVQhTTocnFS0, snapshot 2026-08-10). Extracted verbatim; do not paraphrase.",
+    "entity": "EnablementCompetencyDef",
+    "sobjectFamily": "TOOLING",
+    "count": 7,
+    "note": "These are REFERENCE prompts for the custom-competency conversational-authoring flow (S5). They are also directly installable as-is."
+  },
+  "competencies": [
+    {
+      "MasterLabel": "Business Problem Diagnosis",
+      "DeveloperNameBase": "CCH_BusinessProblemDiagnosis",
+      "SourceCompetencyTemplate": "BUSINESS_PROBLEM_DIAGNOSIS",
+      "Description": "Evaluate how effectively the sales rep diagnoses the business problems faced by the prospect, focusing on identifying pain points, quantifying impacts, probing for root causes, and framing problems in a way that resonates with the...",
+      "EvaluationInstructions": "**PURPOSE:** Evaluate how effectively the sales rep diagnoses the business problems faced by the prospect, focusing on identifying pain points, quantifying impacts, probing for root causes, and framing problems in a way that resonates with the prospect's priorities.\n\n**KEY AREAS TO EVALUATE:**\n\n**1. IDENTIFYING PAIN POINTS**\n**Positive Indicators:**\n- Proactively uncovers specific business challenges\n- Asks targeted questions to surface roadblocks and frustrations\n- Clarifies the impact of challenges on operations or teams\n- Demonstrates curiosity and active listening to explore deeper pain points\n\n**Negative Indicators:**\n- Fails to uncover or clarify key business challenges\n- Asks vague, surface-level questions\n- Misses opportunities to explore additional pain points\n- Does not connect challenges to broader business impacts\n\n**2. QUANTIFYING IMPACTS**\n**Positive Indicators:**\n- Ties pain points to measurable financial or operational outcomes\n- Quantifies the cost, inefficiency, or missed opportunities caused by the challenges\n- Uses metrics or prospect-specific benchmarks to convey impact\n- Highlights urgency by connecting problems to critical business goals\n\n**Negative Indicators:**\n- Fails to connect challenges to measurable outcomes\n- Provides qualitative statements without quantifiable detail\n- Overlooks opportunities to clarify financial or operational impact\n- Relies on assumptions instead of exploring specific data\n\n**3. PROBING FOR ROOT CAUSES**\n**Positive Indicators:**\n- Consistently asks follow-up questions to uncover the root causes behind challenges\n- Demonstrates strategic thinking by exploring underlying trends\n- Asks \"why\" or \"what's driving this\" to dig deeper\n- Aligns root cause exploration with prospect's business priorities\n\n**Negative Indicators:**\n- Does not explore the underlying causes of challenges\n- Stops after identifying surface-level problems\n- Misses opportunities to probe with follow-up questions\n- Fails to connect root causes to strategic solutions\n\n**4. FRAMING PROBLEMS**\n**Positive Indicators:**\n- Reframes challenges using the prospect's language and priorities\n- Summarizes and aligns problems with strategic business goals\n- Highlights the broader impact of challenges on business metrics\n- Positions problems as opportunities for improvement or change\n\n**Negative Indicators:**\n- Fails to reframe or summarize problems effectively\n- Uses generic or unclear language when discussing challenges\n- Misses opportunities to align problems with broader priorities\n- Overlooks the need to position problems as business opportunities\n\n**EXAMPLE STRATEGIC QUESTIONS:**\n- \"What are the top roadblocks preventing your team from hitting their goals this quarter?\"\n- \"How have these challenges impacted your ability to deliver on key initiatives?\"\n- \"What would resolving these issues mean for your business, both financially and operationally?\"\n- \"Can you walk me through what's driving this issue and any trends you've noticed?\"\n\n**EXAMPLE VALUE STATEMENTS:**\n- \"It sounds like the core challenge here is [restate problem], which is causing delays in your processes and limiting efficiency across teams.\"\n- \"This issue seems to be directly impacting your revenue goals, costing your team time and resources that could be redirected to higher-priority initiatives.\"\n- \"Addressing these bottlenecks would help you achieve [specific goal] faster, aligning with your overall priority of streamlining operations.\"\n- \"Based on what you shared, the root cause appears to stem from [specific challenge], creating downstream effects on [team productivity/cost efficiency].\"",
+      "EvaluationScope": "AllCalls"
+    },
+    {
+      "MasterLabel": "Change Management Navigation",
+      "DeveloperNameBase": "CCH_ChangeManagementNavigation",
+      "SourceCompetencyTemplate": "CHANGE_MANAGEMENT_NAVIGATION",
+      "Description": "Evaluate how effectively the sales rep navigates change management during the sales process, focusing on understanding resistance, fostering buy-in, aligning with organizational change goals, and guiding the prospect through uncertainty.",
+      "EvaluationInstructions": "**PURPOSE:** Evaluate how effectively the sales rep navigates change management during the sales process, focusing on understanding resistance, fostering buy-in, aligning with organizational change goals, and guiding the prospect through uncertainty.\n\n**KEY AREAS TO EVALUATE:**\n\n**1. UNDERSTANDING RESISTANCE**\n**Positive Indicators:**\n- Proactively uncovers potential sources of resistance\n- Asks targeted questions to explore concerns or hesitations\n- Acknowledges resistance with empathy and addresses it directly\n- Identifies key risks and mitigates them effectively\n\n**Negative Indicators:**\n- Fails to identify or address resistance\n- Dismisses or overlooks stated concerns\n- Provides generic responses that do not resolve hesitation\n- Misses opportunities to probe for deeper concerns\n\n**2. CREATING BUY-IN**\n**Positive Indicators:**\n- Engages key stakeholders to foster alignment and excitement\n- Proactively involves the customer's team in the change process\n- Develops a collaborative plan to ensure buy-in at all levels\n- Builds confidence by addressing concerns and highlighting value\n\n**Negative Indicators:**\n- Fails to involve stakeholders in the process\n- Misses opportunities to create alignment across teams\n- Provides limited or weak efforts to gain buy-in\n- Lacks clarity in building trust or commitment\n\n**3. ALIGNING WITH CHANGE GOALS**\n**Positive Indicators:**\n- Aligns the solution with the prospect's overarching change objectives\n- Demonstrates understanding of organizational priorities\n- Ties solution benefits to specific change goals\n- Highlights measurable outcomes that support change success\n\n**Negative Indicators:**\n- Fails to align the solution with stated change goals\n- Focuses on tactical features rather than organizational priorities\n- Provides a generic or misaligned narrative\n- Misses opportunities to connect solution outcomes to goals\n\n**4. GUIDING THROUGH UNCERTAINTY**\n**Positive Indicators:**\n- Provides clear and actionable steps to overcome uncertainty\n- Builds confidence through structured guidance and next steps\n- Suggests phased approaches (e.g., pilots, testing) to mitigate risk\n- Proactively offers support and resources to ensure success\n\n**Negative Indicators:**\n- Ignores or downplays uncertainty\n- Provides limited or vague guidance\n- Misses opportunities to suggest actionable strategies\n- Fails to build confidence through clear next steps\n\n**EXAMPLE STRATEGIC QUESTIONS:**\n- \"What challenges or resistance have you faced during similar transitions in the past?\"\n- \"Are there any particular concerns that might slow down adoption within your team?\"\n- \"How can we make this transition as smooth and collaborative as possible?\"\n- \"What would success look like for your team six months after implementing this change?\"\n\n**EXAMPLE NAVIGATION STATEMENTS:**\n- \"To address any pushback, we can work on a phased rollout to ensure your team feels confident and prepared.\"\n- \"You mentioned that streamlining operations is critical. This solution directly aligns with that goal and supports measurable change.\"\n- \"To overcome uncertainty, we can provide detailed training sessions and ongoing support to ensure successful adoption.\"\n- \"Let's map out a change plan together that includes key milestones, stakeholder involvement, and risk mitigation.\"",
+      "EvaluationScope": "AllCalls"
+    },
+    {
+      "MasterLabel": "Discovery Excellence",
+      "DeveloperNameBase": "CCH_DiscoveryExcellence",
+      "SourceCompetencyTemplate": "DISCOVERY_EXCELLENCE",
+      "Description": "Evaluate how effectively the sales rep uncovers customer needs, defines future state, and aligns solutions through discovery conversations.",
+      "EvaluationInstructions": "**PURPOSE:** Evaluate how effectively the sales rep uncovers customer needs, defines future state, and aligns solutions through discovery conversations.\n\n**KEY AREAS TO EVALUATE:**\n\n**1. CURRENT STATE EXPLORATION**\n**Positive Indicators:**\n- Asks detailed questions about current processes\n- Uncovers specific pain points and challenges\n- Gets quantifiable metrics about current problems\n- Explores impact on business/team/individual\n\n**Negative Indicators:**\n- Skips exploring current situation\n- Asks surface-level questions only\n- Misses obvious follow-up opportunities\n- Fails to quantify current challenges\n\n**2. FUTURE STATE DEFINITION**\n**Positive Indicators:**\n- Establishes clear success criteria\n- Uncovers specific desired outcomes\n- Explores timeline expectations\n- Links outcomes to business goals\n\n**Negative Indicators:**\n- Fails to discuss desired outcomes\n- Ignores timeline requirements\n- Misses success criteria\n- Skips business impact discussion\n\n**3. MEDDPICC FUNDAMENTALS**\n**Positive Indicators:**\n- Identifies key decision makers\n- Uncovers budget parameters\n- Establishes clear metrics\n- Finds potential champion\n\n**Negative Indicators:**\n- Misses decision process\n- Ignores budget discussion\n- Skips success metrics\n- Fails to identify champions\n\n**EXAMPLE STRONG QUESTIONS:**\n- \"Walk me through your current process for...\"\n- \"What metrics do you use to measure success?\"\n- \"What would solving this mean for your team?\"\n- \"Who else needs to be involved in this decision?\"",
+      "EvaluationScope": "AllCalls"
+    },
+    {
+      "MasterLabel": "Executive Vision Alignment",
+      "DeveloperNameBase": "CCH_ExecutiveVisionAlignment",
+      "SourceCompetencyTemplate": "EXECUTIVE_VISION_ALIGNMENT",
+      "Description": "Evaluate how effectively the sales rep aligns their solution with executive-level priorities and secures strategic buy-in during conversations.",
+      "EvaluationInstructions": "**PURPOSE:** Evaluate how effectively the sales rep aligns their solution with executive-level priorities and secures strategic buy-in during conversations.\n\n**KEY AREAS TO EVALUATE:**\n\n**1. EXECUTIVE GOALS & PRIORITIES**\n**Positive Indicators:**\n- Uncovers specific strategic priorities\n- Explores long-term business vision\n- Links initiatives to fiscal objectives\n- Discusses organizational impact\n\n**Negative Indicators:**\n- Focuses only on tactical details\n- Misses strategic objectives\n- Fails to explore business priorities\n- Ignores long-term vision\n\n**2. VALUE ARTICULATION**\n**Positive Indicators:**\n- Communicates strategic-level impact\n- Quantifies business outcomes\n- Aligns with executive priorities\n- Presents compelling ROI\n\n**Negative Indicators:**\n- Uses technical language\n- Focuses on features only\n- Misses business impact\n- Fails to quantify value\n\n**3. STRATEGIC ENGAGEMENT**\n**Positive Indicators:**\n- Secures executive commitment\n- Addresses high-level concerns\n- Creates strategic urgency\n- Builds executive sponsorship\n\n**Negative Indicators:**\n- Fails to gain commitment\n- Misses key concerns\n- Lacks executive focus\n- Ignores decision criteria\n\n**EXAMPLE STRATEGIC QUESTIONS:**\n- \"What are your top priorities for the next fiscal year?\"\n- \"How does this align with your growth strategy?\"\n- \"What would success look like at the board level?\"\n- \"How are you measuring strategic impact?\"\n\n**EXAMPLE STRATEGIC VALUE STATEMENTS:**\n- \"This initiative will reduce operational costs by 30%, directly impacting your bottom-line goal.\"\n- \"By automating these processes, we'll free up 25% of your team's capacity for strategic projects.\"\n- \"Our solution aligns with your digital transformation goals by providing enterprise-wide visibility.\"\n- \"This addresses your board's concern about scalability by enabling 3x growth without adding headcount.\"\n- \"We can accelerate your market expansion timeline by 6 months while reducing risk.\"",
+      "EvaluationScope": "AllCalls"
+    },
+    {
+      "MasterLabel": "Multi-Stakeholder Orchestration",
+      "DeveloperNameBase": "CCH_MultiStakeholderOrchestration",
+      "SourceCompetencyTemplate": "MULTI_STAKEHOLDER_ORCHESTRATION",
+      "Description": "Evaluate how effectively the sales rep manages and aligns multiple stakeholders throughout the sales process, focusing on identifying key players, engaging them, building consensus, and managing complex group dynamics to ensure...",
+      "EvaluationInstructions": "**PURPOSE:** Evaluate how effectively the sales rep manages and aligns multiple stakeholders throughout the sales process, focusing on identifying key players, engaging them, building consensus, and managing complex group dynamics to ensure collaboration and buy-in.\n\n**KEY AREAS TO EVALUATE:**\n\n**1. IDENTIFYING STAKEHOLDERS**\n**Positive Indicators:**\n- Proactively identifies all key stakeholders\n- Maps roles, priorities, and influence in the decision process\n- Asks clarifying questions about decision-making dynamics\n- Ensures no critical stakeholders are overlooked\n\n**Negative Indicators:**\n- Fails to identify key decision-makers or influencers\n- Relies on assumptions instead of confirming roles\n- Misses opportunities to clarify decision-making processes\n- Does not uncover hidden stakeholders\n\n**2. ENGAGING STAKEHOLDERS**\n**Positive Indicators:**\n- Actively engages identified stakeholders through tailored outreach\n- Involves relevant team members at appropriate stages\n- Ensures consistent communication and alignment\n- Addresses specific stakeholder needs and priorities\n\n**Negative Indicators:**\n- Fails to engage or interact with key stakeholders\n- Involves stakeholders inconsistently or too late\n- Provides generic outreach not tailored to individual priorities\n- Misses opportunities for proactive alignment\n\n**3. BUILDING CONSENSUS**\n**Positive Indicators:**\n- Aligns stakeholders by addressing concerns and priorities\n- Facilitates agreement on next steps and shared outcomes\n- Resolves conflicts or hesitations with finesse\n- Keeps focus on a unified decision-making path\n\n**Negative Indicators:**\n- Fails to align stakeholders on goals or next steps\n- Ignores conflicts or fails to address disagreements\n- Allows stakeholder misalignment to stall progress\n- Misses opportunities to build trust and secure consensus\n\n**4. MANAGING COMPLEX DYNAMICS**\n**Positive Indicators:**\n- Navigates conflicting priorities with strategic solutions\n- Balances the needs of multiple stakeholders effectively\n- Facilitates open communication to address challenges\n- Demonstrates poise and control in complex group settings\n\n**Negative Indicators:**\n- Struggles to manage conflicting stakeholder interests\n- Avoids addressing difficult group dynamics\n- Focuses on one stakeholder's priorities at the expense of others\n- Fails to provide solutions for navigating group conflicts\n\n**EXAMPLE STRATEGIC QUESTIONS:**\n- \"Who are the key stakeholders we should involve to ensure this decision moves forward seamlessly?\"\n- \"How are priorities across departments influencing this decision?\"\n- \"Is there anyone we haven't yet brought into the conversation who could provide critical input?\"\n- \"What concerns might other stakeholders have that we should address upfront?\"\n\n**EXAMPLE ORCHESTRATION STATEMENTS:**\n- \"To ensure everyone is aligned, let's schedule a working session with your finance and operations leads to address their priorities together.\"\n- \"It sounds like the IT team needs more clarity on integration. I'd be happy to coordinate a technical deep dive to get their input.\"\n- \"I understand marketing and operations have differing goals here. Let's outline how this solution supports both visibility and workflow efficiency.\"\n- \"Before we move forward, let's summarize where everyone stands and identify any open concerns we need to resolve.\"",
+      "EvaluationScope": "AllCalls"
+    },
+    {
+      "MasterLabel": "Product Knowledge",
+      "DeveloperNameBase": "CCH_ProductKnowledge",
+      "SourceCompetencyTemplate": "PRODUCT_KNOWLEDGE",
+      "Description": "Evaluate how effectively the sales rep demonstrates product knowledge during the sales process, focusing on understanding product features, articulating benefits, handling inquiries, and leveraging examples to align with customer needs.",
+      "EvaluationInstructions": "**PURPOSE:** Evaluate how effectively the sales rep demonstrates product knowledge during the sales process, focusing on understanding product features, articulating benefits, handling inquiries, and leveraging examples to align with customer needs.\n\n**KEY AREAS TO EVALUATE:**\n\n**1. UNDERSTANDING OF PRODUCT FEATURES**\n**Positive Indicators:**\n- Accurately describes core features of the product\n- Highlights unique selling propositions (USPs) effectively\n- Demonstrates a strong grasp of technical and functional capabilities\n- Tailors feature explanations to align with customer's specific needs\n\n**Negative Indicators:**\n- Provides inaccurate or incomplete descriptions of features\n- Misses opportunities to emphasize unique selling points\n- Offers generic explanations without customization\n- Demonstrates shallow understanding of the product's technical aspects\n\n**2. ARTICULATION OF PRODUCT BENEFITS**\n**Positive Indicators:**\n- Clearly explains how the product addresses customer pain points\n- Translates features into tangible business benefits\n- Aligns product benefits with the customer's goals and challenges\n- Uses language that resonates with the customer's industry or role\n\n**Negative Indicators:**\n- Focuses solely on features without connecting them to benefits\n- Provides unclear or irrelevant benefit statements\n- Misses opportunities to align benefits with customer needs\n- Uses overly technical or disconnected explanations\n\n**3. HANDLING CUSTOMER INQUIRIES**\n**Positive Indicators:**\n- Confidently and accurately answers customer questions\n- Demonstrates depth of product knowledge when addressing objections\n- Provides thoughtful responses to technical or challenging inquiries\n- Leverages additional resources (e.g., data, integrations) to support answers\n\n**Negative Indicators:**\n- Struggles to answer product-related questions confidently\n- Provides vague or inaccurate responses to inquiries\n- Fails to address technical questions or objections effectively\n- Overlooks opportunities to build credibility through knowledge\n\n**4. USE OF EXAMPLES AND CASE STUDIES**\n**Positive Indicators:**\n- Uses relevant examples or case studies to illustrate product benefits\n- Selects examples that resonate with the customer's industry and challenges\n- Highlights past successes, metrics, or use cases for credibility\n- Demonstrates the product's value through real-world applications\n\n**Negative Indicators:**\n- Fails to incorporate examples or case studies into the conversation\n- Uses irrelevant or generic examples that don't align with the customer\n- Misses opportunities to strengthen explanations with use cases\n- Overlooks metrics or tangible results in provided examples\n\n**5. OVERALL PRODUCT KNOWLEDGE IMPRESSION**\n**Positive Indicators:**\n- Demonstrates expert-level understanding of the product\n- Seamlessly weaves product knowledge into the conversation\n- Tailors explanations to customer needs with confidence\n- Builds trust and credibility through knowledge and articulation\n\n**Negative Indicators:**\n- Displays inadequate or surface-level product understanding\n- Struggles to connect product features and benefits\n- Lacks confidence or accuracy when discussing the product\n- Misses opportunities to differentiate or position the product effectively\n\n**EXAMPLE STRATEGIC QUESTIONS:**\n- \"What specific pain points are you trying to solve with your current solution?\"\n- \"Can you share what outcomes you're looking to achieve with a new platform?\"\n- \"How do integrations or customization capabilities factor into your decision-making process?\"\n- \"Are there specific examples of solutions you've seen work well—or fail—to meet your goals?\"\n\n**EXAMPLE VALUE STATEMENTS:**\n- \"This feature streamlines workflow automation, saving your team an average of 10 hours per week, which aligns with your goal of improving efficiency.\"\n- \"Our platform integrates seamlessly with existing tools like [specific software], reducing implementation time by 30%.\"\n- \"Companies in your industry have seen a 40% reduction in manual errors using our solution, translating directly to improved operational accuracy.\"\n- \"To address your need for scalability, this product ensures performance remains consistent as your team grows by 2x or 3x.\"",
+      "EvaluationScope": "AllCalls"
+    },
+    {
+      "MasterLabel": "Enterprise Value Articulation",
+      "DeveloperNameBase": "CCH_EnterpriseValueArticulation",
+      "SourceCompetencyTemplate": "ENTERPRISE_VALUE_ARTICULATION",
+      "Description": "Evaluate how effectively the sales rep articulates enterprise value during the sales process, focusing on clarity of the value proposition, strategic alignment, quantifiable impact, and competitive differentiation.",
+      "EvaluationInstructions": "**PURPOSE:** Evaluate how effectively the sales rep articulates enterprise value during the sales process, focusing on clarity of the value proposition, strategic alignment, quantifiable impact, and competitive differentiation.\n\n**KEY AREAS TO EVALUATE:**\n\n**1. CLARITY OF VALUE**\n**Positive Indicators:**\n- Clearly communicates the core value of the solution\n- Ties value to specific outcomes relevant to the prospect\n- Uses concise, compelling, and easy-to-understand language\n- Provides examples or metrics to clarify value\n\n**Negative Indicators:**\n- Fails to clearly communicate the solution's value\n- Provides vague or generic statements about benefits\n- Overuses jargon without clarifying the impact\n- Misses opportunities to tie value to specific outcomes\n\n**2. STRATEGIC ALIGNMENT**\n**Positive Indicators:**\n- Aligns the value proposition with the prospect's strategic priorities\n- Demonstrates understanding of the prospect's key initiatives\n- Ties solution benefits to specific organizational goals\n- Articulates how the solution addresses unique challenges\n\n**Negative Indicators:**\n- Does not align the solution with the prospect's strategic goals\n- Provides surface-level or disconnected alignment\n- Focuses on features instead of strategic outcomes\n- Misses opportunities to link solution benefits to priorities\n\n**3. QUANTIFIABLE IMPACT**\n**Positive Indicators:**\n- Articulates measurable outcomes tied to ROI, cost savings, or efficiency\n- Uses specific metrics to highlight financial or operational impact\n- Provides realistic, data-driven projections relevant to the prospect\n- Demonstrates how the solution delivers tangible business value\n\n**Negative Indicators:**\n- Fails to articulate measurable impacts\n- Provides vague or unquantified outcomes\n- Overpromises results without justification\n- Misses opportunities to highlight ROI or financial benefits\n\n**4. COMPETITIVE DIFFERENTIATION**\n**Positive Indicators:**\n- Clearly differentiates the solution from competitors\n- Highlights unique capabilities tied to the prospect's needs\n- Demonstrates a deep understanding of competitive offerings\n- Positions the solution as superior based on context or challenges\n\n**Negative Indicators:**\n- Fails to differentiate the solution from alternatives\n- Provides generic comparisons that lack relevance\n- Overlooks opportunities to highlight competitive strengths\n- Focuses solely on features without differentiating value\n\n**EXAMPLE STRATEGIC QUESTIONS:**\n- \"How do your current challenges align with your broader strategic initiatives this year?\"\n- \"What specific metrics or benchmarks are you looking to achieve with a solution like this?\"\n- \"What has been your experience with other solutions in this space, and where have they fallen short?\"\n- \"How critical is achieving measurable ROI to securing buy-in internally?\"\n\n**EXAMPLE VALUE STATEMENTS:**\n- \"Our solution aligns with your priority to reduce manual workloads by automating repetitive tasks, saving your team up to 15 hours weekly.\"\n- \"Unlike competitors, we deliver actionable insights in real-time and integrate directly into your workflows without additional customization costs.\"\n- \"By improving process efficiency by 30%, you'll not only cut operational costs but also achieve a faster time-to-value for your investment.\"\n- \"You mentioned a focus on scaling without additional headcount. Our platform enables your team to handle 50% more capacity with existing resources.\"",
+      "EvaluationScope": "AllCalls"
+    }
+  ]
+}

package/skills/sales-call-scoring-configure/assets/ootb-competencies.json

@@ -0,0 +1,58 @@
+{
+  "_meta": {
+    "source": "PRD 'Call Coaching Codey configure skill', section 'Current OOTB competency agent instructions' (Google Doc 1XKEDq9ig4du14qWOMv33mHcpBjF-bBwkVQhTTocnFS0, snapshot 2026-08-10). Extracted verbatim; do not paraphrase.",
+    "entity": "EnablementCompetencyDef",
+    "sobjectFamily": "TOOLING",
+    "count": 6
+  },
+  "competencies": [
+    {
+      "MasterLabel": "Active Listening Skills",
+      "DeveloperNameBase": "CCH_ActiveListening",
+      "SourceCompetencyTemplate": "ACTIVE_LISTENING",
+      "Description": "Evaluate the rep's active listening behaviors — reflective statements, paraphrasing, avoiding interruptions, follow-up questions.",
+      "EvaluationInstructions": "Evaluate the rep's active listening behaviors throughout the call. Look for reflective statements, paraphrasing of customer concerns, avoidance of interruptions, and follow-up questions that build on what the customer shared. Score based on how fully the rep engaged with and incorporated the customer's input.",
+      "EvaluationScope": "AllCalls"
+    },
+    {
+      "MasterLabel": "Relationship Building",
+      "DeveloperNameBase": "CCH_RelationshipBuilding",
+      "SourceCompetencyTemplate": "RELATIONSHIP_BUILDING",
+      "Description": "Evaluate personalization, active listening, empathy, and communication-style matching.",
+      "EvaluationInstructions": "Evaluate the rep's use of personalization, active listening, and empathy. Look for moments where the rep referenced prior conversations, showed genuine interest, or matched the customer's communication style. Score based on warmth and authenticity.",
+      "EvaluationScope": "AllCalls"
+    },
+    {
+      "MasterLabel": "Discovery Questioning",
+      "DeveloperNameBase": "CCH_DiscoveryQuestioning",
+      "SourceCompetencyTemplate": "DISCOVERY_QUESTIONING",
+      "Description": "Evaluate depth and quality of discovery questions — business challenges, budget, timeline, decision-making process.",
+      "EvaluationInstructions": "Evaluate the quality and depth of discovery questions asked by the rep. Look for open-ended questions that explore business challenges, budget, timeline, and decision-making process. Score based on how effectively the rep uncovered actionable insights.",
+      "EvaluationScope": "AllCalls"
+    },
+    {
+      "MasterLabel": "Objection Handling",
+      "DeveloperNameBase": "CCH_ObjectionHandling",
+      "SourceCompetencyTemplate": "OBJECTION_HANDLING",
+      "Description": "Evaluate acknowledgment, clarifying questions, reframing, and evidence-based responses to objections.",
+      "EvaluationInstructions": "Evaluate how the rep responded to objections. Look for acknowledgment of the concern, clarifying questions, reframing responses, and evidence-based answers. Score based on how effectively the rep turned objections into opportunities.",
+      "EvaluationScope": "AllCalls"
+    },
+    {
+      "MasterLabel": "Value Proposition Focus",
+      "DeveloperNameBase": "CCH_ValueProposition",
+      "SourceCompetencyTemplate": "VALUE_PROPOSITION_FOCUS",
+      "Description": "Evaluate whether the rep tailored the product/service to the customer's stated needs.",
+      "EvaluationInstructions": "Evaluate whether the rep tailored the product or service presentation to the customer's stated needs. Look for clear benefit articulation, use of relevant examples, and avoidance of irrelevant features. Score based on relevance and clarity of the value proposition.",
+      "EvaluationScope": "AllCalls"
+    },
+    {
+      "MasterLabel": "Closing Urgency",
+      "DeveloperNameBase": "CCH_ClosingUrgency",
+      "SourceCompetencyTemplate": "CLOSING_URGENCY",
+      "Description": "Evaluate close attempts and next-step commitment — trial closes, direct asks, urgency articulation.",
+      "EvaluationInstructions": "Evaluate whether the rep attempted to close or set a concrete next step. Look for trial closes, direct asks, and clear articulation of urgency and the next milestone. Score based on the quality and assertiveness of closing attempts.",
+      "EvaluationScope": "AllCalls"
+    }
+  ]
+}

package/skills/sales-call-scoring-configure/references/admin-communication.md

@@ -0,0 +1,79 @@
+# Admin Communication Guidelines — Full Spec
+
+**CRITICAL**: The `sales-call-scoring-configure` skill serves admin users, not developers. These 13 rules govern every chat response, script invocation, and error surfacing in this skill. The parent SKILL.md holds only the summary; the rationale for each rule lives here.
+
+## Table of contents
+
+- [Rule 1 — Run all bash commands in background](#rule-1--run-all-bash-commands-in-background)
+- [Rule 2 — Monitor progress without showing commands](#rule-2--monitor-progress-without-showing-commands)
+- [Rule 3 — Investigate errors silently](#rule-3--investigate-errors-silently)
+- [Rule 4 — Narrate in plain language](#rule-4--narrate-in-plain-language)
+- [Rule 5 — Hide technical details](#rule-5--hide-technical-details)
+- [Rule 6 — Speak admin language, not entity language](#rule-6--speak-admin-language-not-entity-language)
+- [Rule 7 — Report the outcome, not the steps](#rule-7--report-the-outcome-not-the-steps)
+- [Rule 8 — Don't speculate about internals](#rule-8--dont-speculate-about-internals)
+- [Rule 9 — Check exit codes](#rule-9--check-exit-codes)
+- [Rule 10 — On failure, surface the SOAP fault text](#rule-10--on-failure-surface-the-soap-fault-text)
+- [Rule 11 — Idempotency is silent](#rule-11--idempotency-is-silent)
+- [Rule 12 — Chain automatically, don't hand the baton back](#rule-12--chain-automatically-dont-hand-the-baton-back)
+- [Rule 13 — Ask OOTB-vs-custom once, on first-time competency setup](#rule-13--ask-ootb-vs-custom-once-on-first-time-competency-setup)
+
+## Rule 1 — Run all bash commands in background
+
+Every bash invocation MUST use `run_in_background: true`. Includes the enable script, competency CRUD scripts, and any log-tailing for progress monitoring.
+
+## Rule 2 — Monitor progress without showing commands
+
+You can tail script output to provide progress updates, but keep tails in background. Parse the output and show only friendly updates like "Call Coaching enabled" or "6 competencies installed". Never show the script name, curl command, jq parsing, or raw script output.
+
+## Rule 3 — Investigate errors silently
+
+When something fails, do your diagnosis (check state, retry queries, fix auth) in background without narrating each step. Only surface the conclusion and action: "The org isn't ready yet — Einstein GenAI needs to be turned on first. Doing that now..." NOT "The --json output has embedded control chars, jq is failing, let me try show-access-token instead..."
+
+## Rule 4 — Narrate in plain language
+
+Say "Turning on Call Coaching..." NOT "Running enable-call-scoring.sh Phase 4 SOAP updateMetadata".
+
+## Rule 5 — Hide technical details
+
+No record Ids (`1nA...`), DeveloperNames (`CCH_...`), `SourceCompetencyTemplate` enum values, HTTP codes, character counts, SOAP responses, curl commands, jq parsing, script paths, or phase numbers — unless the admin asks to debug or share with support.
+
+**Exception:** the S9 `verify-ootb-competencies.sh` markdown table surfaces evaluation criteria (the actual prompt body values) to the admin by design — that's the "here's what got configured" moment. See `competency-crud.md` §S9 for the rationale.
+
+## Rule 6 — Speak admin language, not entity language
+
+"Call Coaching", "Coaching Competency", "active/inactive". Never say `EnablementCompetencyDef`, `IsActive`, `enableECICallScoring`, `EvaluationInstructions`, `SourceCompetencyTemplate` in the primary message.
+
+Same S9 exception applies — the verify table's column labels ("Competency", "Evaluation Instructions") are admin-readable English, and the values shown are the prompt bodies themselves (which are content the admin needs to see, not entity metadata).
+
+## Rule 7 — Report the outcome, not the steps
+
+"3 competencies installed" not "ran install-ootb, parsed 6 records, filtered by template, POSTed each".
+
+## Rule 8 — Don't speculate about internals
+
+If a state disagrees with what you expected, translate it into an admin-visible outcome ("Executive Vision Alignment is currently inactive — do you want to reactivate it?"), not a meta-analysis about which query returned what.
+
+## Rule 9 — Check exit codes
+
+Always parse success/failure and translate technical errors to admin-friendly messages ("The org's on the wrong sales-cloud arm for this skill — needs ECI").
+
+## Rule 10 — On failure, surface the SOAP fault text
+
+So the admin can share it with support if needed. Redact session tokens (the `soap.sh` library does this).
+
+## Rule 11 — Idempotency is silent
+
+If the feature is already on or a competency is already installed, say so briefly and move on — do not re-run the write.
+
+## Rule 12 — Chain automatically, don't hand the baton back
+
+When `enable-call-scoring.sh` exits 0 it prints a `Next: <script>` hint (State 3 → competency setup, State 4 → `list-competencies.sh`, fresh enable → same as State 3). Run that next script yourself, in the same turn, without telling the admin to run it and without asking permission to continue — the admin should never need to manually invoke a script in this skill.
+
+**Exception: the State 3 "Next" hint is not a green light to install the OOTB set unasked.** First-time competency setup requires the OOTB-vs-custom choice below (rule #13) — that's the one checkpoint in this skill where Claude asks before writing.
+
+## Rule 13 — Ask OOTB-vs-custom once, on first-time competency setup
+
+When state detection lands on State 3 (Call Coaching enabled, zero competencies) and the admin's intent is "set up competencies" / "install competencies" / an unqualified continuation of the enable flow (not an explicit "install the OOTB set" or "create a custom competency" ask), run `install-ootb-competencies.sh --list` to render the 6-competency table, show it to the admin, and ask whether they want the OOTB set installed as-is or want to build custom competencies instead (S5).
+
+If the admin's original request already named OOTB or custom explicitly, skip the question and proceed — this checkpoint exists for the ambiguous "set this up for me" case, not to re-litigate an explicit ask.