# Skills

Endpoints for exploring skills, abilities, and knowledge domains with their AI resilience scores.

## List Skills

```http
GET /skills
```

List all skills, abilities, and knowledge with AI resilience scores.

**Access:** All tiers

### Parameters

| Parameter | Type   | Required | Default               | Description                                  |
| --------- | ------ | -------- | --------------------- | -------------------------------------------- |
| `type`    | string | No       | `all`                 | `skills`, `abilities`, `knowledge`, or `all` |
| `sort_by` | string | No       | `ai_resilience_score` | Sort field                                   |
| `limit`   | int    | No       | 50                    | Max results (1-120)                          |

### Response

```json
{
  "count": 120,
  "requirements": [
    {
      "element_id": "2.B.1.d",
      "name": "Negotiation",
      "type": "Skills",
      "description": "Bringing others together and trying to reconcile differences",
      "ai_resilience_score": 1.0
    },
    {
      "element_id": "2.A.1.d",
      "name": "Speaking",
      "type": "Skills",
      "description": "Talking to others to convey information effectively",
      "ai_resilience_score": 0.98
    }
  ]
}
```

### Example

```bash
# Get most AI-resilient skills
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.maidenlabs.tools/skills?type=skills&sort_by=ai_resilience_score&limit=10"

# Get abilities sorted alphabetically
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.maidenlabs.tools/skills?type=abilities&sort_by=name"
```

***

## Get Skill Profile

```http
GET /skills/{element_id}
```

Get detailed profile for a specific skill.

**Access:** Professional, Enterprise

### Path Parameters

| Parameter    | Type   | Description                         |
| ------------ | ------ | ----------------------------------- |
| `element_id` | string | O\*NET element ID (e.g., "2.A.1.a") |

### Response

```json
{
  "element_id": "2.B.3.e",
  "name": "Programming",
  "type": "Skills",
  "description": "Writing computer programs for various purposes",
  "ai_resilience_score": 0.26,
  "benchmark_coverage": {
    "total_benchmarks": 47,
    "top_benchmarks": ["HumanEval", "MBPP", "APPS"],
    "avg_relevance": 0.72
  },
  "job_prevalence": {
    "total_jobs": 156,
    "avg_relevance": 0.68,
    "top_jobs": [
      {
        "soc_code": "15-1252.00",
        "title": "Software Developers",
        "relevance": 0.95
      },
      {
        "soc_code": "15-1251.00",
        "title": "Computer Programmers",
        "relevance": 0.92
      }
    ]
  }
}
```

### Example

```bash
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.maidenlabs.tools/skills/2.B.3.e"
```

***

## Semantic Search Skills

```http
GET /skills/search/semantic
```

Search skills using natural language queries.

**Access:** Professional, Enterprise

### Parameters

| Parameter | Type   | Required | Default | Description            |
| --------- | ------ | -------- | ------- | ---------------------- |
| `q`       | string | Yes      | -       | Natural language query |
| `limit`   | int    | No       | 10      | Max results (1-50)     |

### Response

```json
{
  "query": "ability to convince others",
  "count": 5,
  "requirements": [
    {
      "element_id": "2.B.1.c",
      "name": "Persuasion",
      "type": "Skills",
      "similarity": 0.92,
      "ai_resilience_score": 0.95
    },
    {
      "element_id": "2.B.1.d",
      "name": "Negotiation",
      "type": "Skills",
      "similarity": 0.88,
      "ai_resilience_score": 1.0
    }
  ]
}
```

### Example

```bash
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.maidenlabs.tools/skills/search/semantic?q=working+with+numbers"
```

***

## Skill Gap Analysis

```http
POST /skills/gap
```

Analyze skill gaps for career transition.

**Access:** Professional, Enterprise

### Request Body

```json
{
  "current_skills": ["Programming", "Critical Thinking", "Mathematics"],
  "target_job": "13-2011.00"
}
```

### Response

```json
{
  "target_job": {
    "soc_code": "13-2011.00",
    "title": "Accountants and Auditors"
  },
  "skill_coverage": 0.42,
  "transferable_skills": [
    {
      "name": "Critical Thinking",
      "relevance_in_target": 0.85,
      "ai_resilience": 0.72
    },
    {
      "name": "Mathematics",
      "relevance_in_target": 0.92,
      "ai_resilience": 0.94
    }
  ],
  "gap_skills": [
    {
      "name": "Judgment and Decision Making",
      "relevance_in_target": 0.88,
      "ai_resilience": 0.43,
      "priority": "high"
    },
    {
      "name": "Complex Problem Solving",
      "relevance_in_target": 0.82,
      "ai_resilience": 0.60,
      "priority": "high"
    }
  ],
  "skill_match_score": 0.65
}
```

### Example

```bash
curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"current_skills": ["Programming"], "target_job": "13-2011.00"}' \
  "https://api.maidenlabs.tools/skills/gap"
```

***

## Requirement Categories

Cubit includes 120 requirements across three categories:

### Skills (35)

Developed capacities that facilitate learning or performance:

| Category                | Examples                                       |
| ----------------------- | ---------------------------------------------- |
| Basic Skills            | Reading Comprehension, Writing, Speaking       |
| Social Skills           | Coordination, Persuasion, Negotiation          |
| Complex Problem Solving | Complex Problem Solving                        |
| Technical Skills        | Programming, Equipment Maintenance             |
| Systems Skills          | Systems Analysis, Judgment and Decision Making |
| Resource Management     | Time Management, Management of Personnel       |

### Abilities (52)

Enduring attributes that influence performance:

| Category    | Examples                                       |
| ----------- | ---------------------------------------------- |
| Cognitive   | Deductive Reasoning, Memorization, Originality |
| Psychomotor | Manual Dexterity, Reaction Time                |
| Physical    | Static Strength, Stamina                       |
| Sensory     | Near Vision, Hearing Sensitivity               |

### Knowledge (33)

Organized sets of principles and facts:

| Category        | Examples                          |
| --------------- | --------------------------------- |
| Business        | Administration, Economics, Sales  |
| Manufacturing   | Production, Food Production       |
| Engineering     | Computers, Engineering, Design    |
| Science         | Mathematics, Physics, Biology     |
| Health Services | Medicine, Therapy                 |
| Education       | Education and Training            |
| Arts            | Fine Arts, Communications         |
| Law             | Public Safety, Law and Government |

***

## AI Resilience Interpretation

| Score Range | Interpretation       | Examples                               |
| ----------- | -------------------- | -------------------------------------- |
| 0.90 - 1.00 | Very high resilience | Negotiation, Speaking, Time Management |
| 0.70 - 0.89 | High resilience      | Coordination, Critical Thinking        |
| 0.50 - 0.69 | Moderate resilience  | Complex Problem Solving, Originality   |
| 0.30 - 0.49 | Low resilience       | Systems Analysis, Problem Sensitivity  |
| 0.00 - 0.29 | Very low resilience  | Programming, Quality Control Analysis  |

Skills with low AI resilience are those where current AI models demonstrate strong performance on relevant benchmarks.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.maidenlabs.tools/api-reference/skills.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.