Designing Skills Gap Analysis Reports Comparing Agent Proficiencies Against Queue Requirements
What This Guide Covers
This guide details the architectural and implementation steps required to build a recurring skills gap analysis pipeline that ingests agent proficiency matrices and queue routing configurations, calculates coverage deficits against scheduled demand, and outputs structured reports for workforce planning and training teams. When complete, you will have an automated reporting mechanism that identifies exact skill shortages by time interval, surfaces over-allocated agents across competing queues, and triggers alerts when proficiency coverage falls below defined thresholds.
Prerequisites, Roles & Licensing
- Genesys Cloud CX: CX 2 or CX 3 license, WFM Add-on (for schedule and demand alignment),
Analytics > Report > Create/Edit,Routing > Queue > View,Routing > Skill > View,Routing > User > View - NICE CXone: CXone Platform license, Workforce Management module,
Reporting > Create Report,Routing > Skills > Manage,Routing > Queues > Configure,Users > View - OAuth Scopes:
analytics:report:view,routing:queue:view,routing:skill:view,routing:user:view,reporting:reports:read - External Dependencies: BI visualization layer (Tableau, PowerBI, or Looker), data orchestration framework (Airflow, Cloud Run, or Azure Functions), WFM schedule export capability
The Implementation Deep-Dive
1. Skill Taxonomy Normalization and Routing Rule Mapping
Contact center platforms model skills differently, and routing rules consume skills in ways that are not immediately visible in standard UI dashboards. Before writing any query, you must establish a normalized skill taxonomy that aligns platform-specific proficiency levels with queue requirements.
In Genesys Cloud, skills are hierarchical with proficiency levels ranging from 1 to 5. Queues reference skills through routing rules that specify a minimum proficiency threshold. In NICE CXone, skills are flat or categorized with numerical proficiency scores, and flows reference skills through routing blocks that evaluate proficiency against a configured minimum. Both platforms allow fallback behaviors, which complicates gap calculations if not explicitly mapped.
You must extract the routing configuration and translate it into a requirement matrix. The matrix must contain the queue identifier, the required skill identifier, the minimum proficiency threshold, and the routing priority. If a queue uses multiple skills with OR logic, you must record that logical relationship explicitly.
The Trap: Assuming skill assignment equals routing eligibility. An agent may have Spanish_L2 assigned, but if the queue routing rule requires Spanish_L2 with a minimum proficiency of 4, and the agent only has level 3, the agent will never receive calls routed to that queue. Reporting on assignment alone produces false coverage metrics that mask actual capacity gaps.
Architectural Reasoning: Normalize all skills into a unified schema before joining with agent data. Use a structure like {skill_id, hierarchy_path, proficiency_level, effective_date, expiration_date, routing_priority}. Store this in your orchestration layer or data warehouse. This decouples the reporting logic from platform UI changes and allows you to recalculate gaps when WFM schedules shift without re-querying the CCaaS platform repeatedly.
Extract skill definitions using the platform APIs. For Genesys Cloud:
GET /api/v2/routing/skills
Authorization: Bearer <access_token>
For NICE CXone:
GET /api/v2/routing/skills
Authorization: Bearer <access_token>
Map queue routing rules by extracting queue configurations. Genesys Cloud returns routing rules in the queue object:
GET /api/v2/routing/queues/{queueId}
Authorization: Bearer <access_token>
The response contains a routingRules array. Filter for rules where type equals skills and extract minProficiency. CXone returns routing configurations in the flow or queue metadata. You will need to parse the flow JSON or use the /api/v2/routing/queues/{queueId} endpoint to retrieve associated routing requirements.
Store the normalized requirement matrix in your processing pipeline. This matrix becomes the left side of your gap calculation join.
2. Query Construction and Cross-Platform Data Extraction
You must extract agent skill assignments, scheduled shifts, and status restrictions. Real-time availability APIs are unsuitable for gap analysis because they reflect instantaneous state rather than planned capacity. Use historical reporting endpoints or WFM schedule exports to capture planned coverage.
In Genesys Cloud, the Reporting API provides ad-hoc query capabilities that return agent skill coverage over time intervals. Construct a query that groups by user ID, skill ID, and time bucket. The query must filter for active users and exclude those with restriction statuses that prevent routing.
POST /api/v2/analytics/reporting/query
Content-Type: application/json
Authorization: Bearer <access_token>
{
"dateFrom": "2024-01-01T00:00:00Z",
"dateTo": "2024-01-08T00:00:00Z",
"interval": "PT15M",
"groupBy": ["userId", "skillId"],
"aggregations": [
{
"name": "scheduledCapacity",
"type": "sum",
"statistic": "sum"
}
],
"filter": {
"type": "and",
"clauses": [
{
"type": "equals",
"path": "user.status",
"value": "available"
},
{
"type": "notIn",
"path": "user.restrictionStatuses",
"value": ["training", "lunch", "meeting"]
}
]
}
}
In NICE CXone, use the reporting execution endpoint to pull scheduled skill coverage. Configure a report template that groups by agent, skill, and time slice, then execute it via API.
POST /api/v2/reports/{reportId}/execute
Content-Type: application/json
Authorization: Bearer <access_token>
{
"parameters": {
"dateRange": {
"start": "2024-01-01T00:00:00Z",
"end": "2024-01-08T00:00:00Z"
},
"groupBy": ["agentId", "skillId", "timeSlot"],
"metrics": ["scheduledAgents", "qualifiedAgents"]
}
}
The Trap: Ignoring pagination and rate limits during bulk extraction. Both platforms enforce strict rate limits on reporting endpoints. Genesys Cloud returns paginated results with nextPageToken. CXone uses cursor-based pagination. If you do not implement exponential backoff and token chaining, your extraction job will fail mid-run, producing incomplete datasets that skew gap calculations downward.
Architectural Reasoning: Implement a dedicated extraction worker that handles pagination natively. Cache the extracted datasets in a time-series store or columnar database. Align all timestamps to UTC during extraction, then convert to agent local time only during visualization. This prevents daylight saving time shifts from creating phantom gaps at 2 AM or 3 AM. Reference the WFM Schedule Alignment patterns documented in workforce optimization guides to ensure your time buckets match shift boundaries.
3. Gap Calculation Logic and Proficiency Thresholding
The core of the analysis is the gap calculation. You must compare required coverage against qualified coverage per time interval. The formula is straightforward: Gap = Required_Agents - Qualified_Agents. The complexity lies in determining Qualified_Agents accurately.
Qualified agents must meet four conditions:
- Assigned the required skill
- Proficiency level meets or exceeds the queue minimum
- Scheduled for the time interval
- Not restricted by status or compliance hold
You must also handle overlapping skills. If Queue A requires English_L1 OR Spanish_L1, an agent with either skill qualifies. If Queue B requires English_L1 AND Compliance_Finance, the agent must possess both. Your calculation engine must evaluate logical operators per queue.
Implement a time-bucketed evaluation loop. For each 15-minute interval:
- Load the requirement matrix for active queues
- Load the agent skill matrix for that interval
- Apply proficiency threshold filters
- Apply status restriction filters
- Calculate qualified count per queue
- Subtract qualified count from WFM forecast demand
- Record positive values as deficits, negative values as surplus
The Trap: Double-counting agents across multiple queues without capacity constraints. An agent scheduled from 9:00 to 13:00 with Spanish_L2 and English_L2 will appear as qualified for both Queue A and Queue B. If both queues show a deficit, the report will recommend hiring two agents when one crossover agent can cover both. This inflates headcount projections and distorts training budgets.
Architectural Reasoning: Apply a greedy allocation algorithm or a simple linear programming solver to distribute agent capacity across competing queues. Sort queues by priority or forecast demand. Assign agent capacity to the highest priority queue first, then decrement remaining capacity. If capacity reaches zero, mark lower priority queues as partially covered. For production environments, use a constraint solver (OR-Tools or PuLP) to optimize coverage across all queues simultaneously. This approach mirrors how the actual routing engine evaluates agent availability and prevents phantom surplus.
Store the calculated gaps in a structured format:
{
"interval_start": "2024-01-01T09:00:00Z",
"interval_end": "2024-01-01T09:15:00Z",
"queue_id": "q_finance_support",
"required_skill": "finance_compliance",
"min_proficiency": 4,
"forecast_demand": 12,
"qualified_agents": 8,
"gap": 4,
"overallocated_agents": 3,
"recommendation": "increase_shift_coverage"
}
4. Report Orchestration and Automated Distribution
Static reports decay in value within 24 hours. You must orchestrate the pipeline to run on a cadence that matches your WFM planning cycle, typically daily or weekly. Distribute the output through a BI dashboard for trend analysis and through messaging channels for immediate action.
In Genesys Cloud, use the Reporting API subscriptions to schedule ad-hoc queries or export to S3. Configure a subscription that triggers on a cron schedule and pushes JSON payloads to a cloud storage bucket.
POST /api/v2/analytics/reporting/subscriptions
Content-Type: application/json
Authorization: Bearer <access_token>
{
"name": "SkillsGap_Daily",
"type": "analytics",
"schedule": {
"type": "cron",
"expression": "0 6 * * 1-5"
},
"destination": {
"type": "s3",
"bucket": "cc-analytics-reports",
"path": "skills-gap/{date}/"
},
"query": {
"dateFrom": "{{yesterday_start}}",
"dateTo": "{{yesterday_end}}",
"interval": "PT15M",
"groupBy": ["userId", "skillId", "queueId"],
"aggregations": [{"name": "qualifiedCount", "type": "sum", "statistic": "sum"}]
}
}
In NICE CXone, use the report scheduler or webhook integrations to push executed reports to an external endpoint. Configure the scheduler to run the report template and POST the results to your orchestration layer.
Your orchestration function must:
- Ingest the raw reporting data
- Join with the normalized requirement matrix
- Execute the gap calculation logic
- Aggregate deficits by skill, queue, and day
- Publish to BI warehouse
- Trigger alerts when
gap > threshold
The Trap: Alert fatigue from unthresholded notifications. If you trigger a Slack or Teams message for every 15-minute interval where a gap exists, operations managers will disable the integration. You must aggregate gaps by business hour or shift, apply a minimum deficit threshold (e.g., gap >= 2 agents), and include remediation context in the payload.
Architectural Reasoning: Design the alerting layer to mirror the routing engine’s priority logic. Only escalate when the gap impacts forecasted service level targets. Include the exact skill ID, minimum proficiency required, and the list of agents who are closest to qualifying (e.g., proficiency 3 when 4 is required). This enables training teams to target upskilling campaigns rather than triggering emergency hiring. Reference the Speech Analytics Quality Alignment patterns to correlate skill gaps with actual call disposition outcomes, ensuring you are addressing real performance deficits rather than theoretical coverage shortfalls.
Validation, Edge Cases & Troubleshooting
Edge Case 1: Skill Expiration Misalignment
The failure condition: The report shows zero gaps for a compliance-heavy queue, but actual service levels degrade during the reporting period. Agents are dropping out of routing eligibility mid-shift.
The root cause: Skills with expiration dates are not being evaluated against the current timestamp during the calculation window. The extraction query pulls skill assignments but does not filter for expiration_date > current_interval. Agents with expired certifications remain in the qualified pool artificially.
The solution: Add a temporal filter to the skill matrix join. During extraction, pull the expiration_date and effective_date fields from the skill assignment payload. In the calculation loop, evaluate if current_interval >= effective_date AND current_interval <= expiration_date. If your platform does not expose expiration dates in the reporting API, query the user skill assignment endpoints directly and cache the expiration metadata. Refresh this cache daily to prevent stale data from skewing coverage metrics.
Edge Case 2: Overlapping Queue Routing with Fallback Skills
The failure condition: The report indicates a severe deficit for a primary queue, but the actual queue performance shows acceptable handle times and wait times. The gap calculation appears accurate, but operations teams report the metric is misleading.
The root cause: The queue uses a fallback skill or a secondary routing rule that activates when the primary skill pool is exhausted. The gap analysis only evaluates the primary skill requirement and ignores the fallback behavior. When the primary pool depletes, the routing engine automatically routes to agents with the fallback skill, masking the deficit in real-time performance.
The solution: Map all routing rules for each queue, including fallback, overflow, and time-based routing configurations. Modify the gap calculation to evaluate the union of all active skill pools for the given interval. If fallback routing is time-gated, apply the fallback logic only during the specified windows. Document the fallback behavior in the report output so workforce planners understand that the gap represents primary pool coverage, not total queue capacity. If your WFM system supports multi-skill routing forecasts, align the gap report with the WFM’s multi-skill optimization engine to prevent conflicting recommendations.