| name | scoring-engine |
| description | Configurable rule-based scoring engine for multi-dimensional weighted evaluation. Rules are parameterized in YAML configs — change rules without changing the Skill. 4-Phase orchestrated pipeline: Phase1(Info-Extractor) → Phase2(Knowledge-RAG) → Phase3(Data-Analyst) → Phase4(Report-Generator). Use cases: customer opportunity scoring, churn risk assessment, supplier evaluation, partner tiering, and any multi-dimensional weighted scoring needs. Triggers: scoring, rate, opportunity scoring, customer scoring, churn risk, rule engine, multi-dimensional scoring, weighted scoring, rule hit detection. Activated when a user provides a business object (e.g., customer profile) and requests scoring against configurable rules.
|
| name_cn | Scoring-Engine 规则引擎评分组件 |
| description_cn | 基于可配置规则和权重对业务对象做多维度评分，规则参数化存在YAML中，业务变了改配置不用改Skill |
| version | 1.0.0 |
| author | yuzhaopeng |
| license | Apache-2.0 |
Scoring-Engine
Core Philosophy
Not a single rule, but a configurable rule engine — ordinary Skills hard-code rules in prompts; advanced Skills parameterize rules so that when business changes, you update the YAML config, not the Skill.
Orchestration Architecture
This Skill uses a 4-Phase mandatory component orchestration, driven by the phase-orchestrator skill to execute 4 independent sub-Agents. Each Phase runs in its own Agent; data is passed between Phases as structured JSON. No Phase may be skipped; no free-text substitution for component output is allowed.
┌─ Orchestrator Agent ──────────────────────────────┐
│ task → Sub-Agent1: Info-Extractor (Object Parse) │
│ task → Sub-Agent2: Knowledge-RAG (Rule Loading) │
│ task → Sub-Agent3: Data-Analyst (Score Calc) │
│ task → Sub-Agent4: Report-Generator (Report Gen) │
└───────────────────────────────────────────────────┘
Execution: Load the skill tool with name: "phase-orchestrator" and follow its generic dispatch flow. This Skill provides complete Phase prompt templates (see references/pipeline-phases.md). The current Agent reads templates, replaces placeholders, and constructs pipeline_config for the orchestrator. The orchestrator contains no scoring-engine business logic — it only handles dispatch, data passing, and fallback.
Degraded Mode: If the task tool is unavailable or phase-orchestrator fails to load, fall back to single-Agent mode: the current Agent manually executes all 4 Phases per the processing rules in references/pipeline-phases.md, annotating [Degraded: multi-Agent orchestration unavailable].
Detailed orchestration protocol (I/O JSON contracts, degradation strategy, data passing format) is in references/orchestration.md.
Sub-Agent prompt templates are in phase-orchestrator's references/task-prompts.md.
Input Parameters
Required
| Parameter | Type | Description |
|---|
target_object | JSON object | Business object to score, e.g. {name:"Acme Manufacturing Corp", level:"Tier-1", revenue:"50M", existing_products:["Product A"], cooperation_years:2, recent_complaints:1, competitor_contact:true} |
scoring_config_name | string | Scoring rule set name, e.g. "Customer Opportunity Scoring v2", "Customer Churn Risk v1" |
Optional
| Parameter | Type | Default | Description |
|---|
custom_weights | JSON object | null | Custom weight overrides, e.g. {"Business Scale":0.25,"Service Risk":0.15}. Unspecified dimensions keep default weights. |
rule_adjustment | boolean | true | Enable rule adjustment (auto-adjust total when special rules are hit) |
output_format | enum | markdown | Report output format: markdown / json / table |
Phase 1 - Object Parsing (Info-Extractor)
Mandatory load: Call skill tool with name: "info-extractor"
Input Contract:
- Raw text: serialized JSON of
target_object
- Extraction template: 6 scoring dimension field mappings
Field mapping:
- Business Scale: revenue / annual_revenue → annual revenue
- Technology Adoption: existing_products / it_products → existing product list
- Solution Fit: match_products / potential_products → matched product list
- Partnership History: cooperation_years / contract_history → partnership duration
- Service Risk: recent_complaints / complaint_count → complaints in last 3 months
- Competitive Landscape: competitor_contact / competitor_status → competitor contact status
Output Contract (must be structured JSON):
{
"phase": "extraction",
"dimensions": {
"Business Scale": {"raw_value": "50M", "field": "revenue"},
"Technology Adoption": {"raw_value": ["Product A","Product B"], "field": "existing_products"},
"Solution Fit": {"raw_value": ["Solution X","Solution Y"], "field": "match_products"},
"Partnership History": {"raw_value": 2, "field": "cooperation_years"},
"Service Risk": {"raw_value": 1, "field": "recent_complaints"},
"Competitive Landscape": {"raw_value": true, "field": "competitor_contact"}
},
"missing_dimensions": []
}
Missing dimensions are annotated "raw_value": null and listed in missing_dimensions.
Degradation: If info-extractor fails to load, this Skill manually extracts per field mapping rules, same output format, annotated [Degraded: Info-Extractor not loaded].
Phase 2 - Rule Loading (Knowledge-RAG)
Mandatory load: Call skill tool with name: "knowledge-rag"
Input Contract:
- Knowledge document: references/scoring-rules.md as RAG source
- Query:
"Load scoring rule set: {scoring_config_name}, return dimension list, weights, scoring criteria, special rules"
Core Task: Retrieve the complete YAML config block for scoring_config_name from scoring-rules.md and return structured rule data.
Output Contract (must be structured JSON):
{
"phase": "rule_loading",
"config_name": "Customer Opportunity Scoring v2",
"dimensions": [
{"name": "Business Scale", "weight": 0.20, "source_field": "revenue", "scoring_criteria": [...]},
...
],
"special_rules": [
{"name": "Tier-1 Churn Alert", "conditions": [...], "score_adjustment": -20, "reason": "...", "suggestion": "..."},
...
],
"grade_thresholds": {"high": 80, "medium": 60, "low": 0},
"action_suggestions": {"high": "...", "medium": "...", "low": "..."},
"custom_weights_applied": false,
"weight_normalization_warning": null
}
Weight Merge Logic (executed within this Phase):
- If
custom_weights is non-null, merge into default weights (override only specified dimensions)
- Check if weight sum equals 1; if not, normalize and set
weight_normalization_warning: "Weight sum is X, auto-normalized. Consider reviewing weight settings."
- Set
custom_weights_applied: true
Error Handling: If scoring_config_name does not exist in scoring-rules.md, error: "Rule set not found. Please confirm the name or create the rule set first." Terminate orchestration.
Degradation: If knowledge-rag fails to load, this Skill directly reads references/scoring-rules.md and parses the corresponding config, annotated [Degraded: Knowledge-RAG not loaded].
Phase 3 - Score Calculation (Data-Analyst)
Mandatory load: Call skill tool with name: "data-analyst"
Input Contract:
- Phase 1 extraction result
- Phase 2 rule_loading result
- Analysis mode:
"scoring" (custom scoring analysis mode)
- Analysis instruction: score per criteria → weighted calculation → rule hit detection
Scoring Calculation Rules:
- Dimension Scoring: Each dimension matches
raw_value against scoring_criteria for a raw score (1-10). raw_value null → raw score = null.
- Weighted Calculation:
weighted_score = raw_score × weight × 10 (null → 0). total = Σ weighted_score (max 100).
- Grade Determination: High (≥80) | Medium (60-79) | Low (<60)
- Rule Hit Detection (when
rule_adjustment=true): iterate special_rules; if all conditions are true, rule is hit; execute score_adjustment; floor at 0.
Output Contract (must be structured JSON):
{
"phase": "scoring",
"scoring_matrix": [
{"Dimension": "Business Scale", "Weight": "20%", "Raw Value": "50M", "Raw Score": 8, "Weighted Score": 16.0, "Rule Hit": "✓ Pass"},
...
],
"summary": {
"raw_total": 63.5,
"rule_adjustments": [
{"rule": "Tier-1 Churn Alert", "conditions_check": [{"field":"level","expected":"Tier-1","actual":"Tier-1","hit":true},...], "adjustment": -20}
],
"final_total": 43.5,
"grade": "Low",
"action_suggestion": "Urgent follow-up recommended..."
},
"all_dimensions_null": false
}
Error Handling:
- Rule hit causes total < 0 → set total to 0, annotate "Multiple risk rules stacked. Strong attention recommended."
- All dimension raw scores are null → error: "Target object is missing all scoring dimension data. Cannot score." Terminate orchestration.
Degradation: If data-analyst fails to load, this Skill manually calculates per the rules above, annotated [Degraded: Data-Analyst not loaded].
Phase 4 - Report Generation (Report-Generator)
Mandatory load: Call skill tool with name: "report-generator"
Input Contract:
- report_type:
"customer_brief"
- Phase 3 scoring result
- output_format: user-specified format
Report Must Include 5 Modules:
Module 1 - Scoring Matrix Table
| Dimension | Weight | Raw Score | Weighted Score | Rule Hit |
|---|
| Business Scale | 20% | 8 | 16.0 | ✓ Pass |
| ... | ... | ... | ... | ... |
| Total | 100% | — | XX | — |
Rule hit labels: ✓ Pass / ⚠️ Risk / — No rule
Module 2 - Summary Row: total score, grade (High/Medium/Low), recommended action
Module 3 - Rule Config Display: currently active scoring rule YAML snippet (shows rules are parameterized)
Module 4 - Hit Rule Explanation: each hit rule shows rule name, per-condition match (✓/✗), adjustment value, adjustment reason
Module 5 - Sensitivity Note: "Modify weights/rules and re-run to take effect. No Skill code changes needed."
Degradation: If report-generator fails to load, this Skill manually generates report per the 5-module format above, annotated [Degraded: Report-Generator not loaded].
Security Requirements
- Customer names are anonymized as "Client A/B/C" during archiving
- Scoring rules are core business assets; archive with label "Internal reference, do not distribute"
- When total score < 50 triggers alert, report must note "This conclusion is for internal reference only and should not be the sole basis for client classification"
- Do not display contract amounts directly in output; show only "Met/Not Met"
Error Handling Quick Reference
| Error Scenario | Handling |
|---|
| target_object missing dimension data | Annotate "Data missing", raw score null, weighted score 0, highlight |
| scoring_config_name not found | Error: "Rule set not found. Please confirm the name or create the rule set first." Terminate |
| Custom weight sum ≠ 1 | Auto-normalize with warning |
| Rule hit causes total < 0 | Set total to 0, annotate "Multiple risk rules stacked. Strong attention recommended." |
| All dimension raw scores null | Error: "Target object is missing all scoring dimension data. Cannot score." Terminate |
| Component load failure | Activate degradation strategy, annotate degraded mode, output format unchanged |
Rule Library and Orchestration Protocol
