Skill Atlas

Detail-SchnellnavigationQuick Navigation

1. Was ist ein Skill?1. What is a Skill?

Ein Skill ist eine verifizierte, dokumentierte Fähigkeit, die ein Actor besitzt und die von einer Role gefordert werden kann, um eine bestimmte Art von Arbeit auszuführen.

Universal: Skills sind typ-agnostisch. Mensch und Agent können identische Skills besitzen. Skills sind registriert, versioniert und abfragbar — kein Actor-Typ-Privileg.

Skill YAML-AnatomieSkill YAML Anatomy

id: skill-eng-code-review-python
version: 1
kind: skill
status: active                    # active | deprecated | experimental

name: "code-review-python"
category: engineering
domain: technical                 # technical | process | domain-specific | meta
description: >
  Can review Python code for correctness, style,
  performance, and security.
required_by_roles: [reviewer]

evidence_class: mcp_verified      # see Section 2
evidence:
  - type: test_suite_pass
    id: ev-python-review-001
    link: tests/skill-evidence/python-review-suite.py
    verified_at: 2024-01-15T09:00:00Z
    verified_by: validator-bot

proficiency_model:                # see Section 3
  - level: novice
    description: can review with guidance
    verification: simple test pass
  - level: practitioner
    description: reviews independently
    verification: artifact review + peer sign-off
  - level: expert
    description: mentors others
    verification: third-party certification or mentorship evidence

prerequisites: [skill-eng-python-basics]
conflicts_with: []

registered_at: 2024-01-10T08:00:00Z
registered_by: ops-team
maintained_by: ops-team
last_verified: 2024-01-15T09:00:00Z
sunset_date: never

tags: [python, code-quality, review]
related_skills: [skill-eng-testing-unit-integration]

2. Evidence-Klassen2. Evidence Classes

Jeder Skill-Claim muss in eine der vier Evidence-Klassen eingestuft werden. HITL-Anforderungen steigen mit sinkender Verifikationsstärke.

Evidence-TypenEvidence Types

3. Proficiency-Modell3. Proficiency Model

Drei Stufen — optionales Feld. Wenn angegeben, ist die Stufe nachweispflichtig.

Fehlt das proficiency_model-Feld, gilt der Skill als binär: vorhanden/nicht vorhanden.

4. Skill-Domänen & Kategorien4. Skill Domains & Categories

Vier übergeordnete Domänen, jede mit definierten Kategorien und Beispiel-Skills.

5. Top-Level Skill-Mapping5. Top-Level Skill Mapping

Jede Verzeichnis-Ebene im Workspace hat einem festgelegten Skill-Typ. Quelle: top-level-skill-mapping.yaml

Contract-Felder in top-level-skill-mapping.yaml

# Auszug aus top-level-skill-mapping.yaml
required-skill:
  directories: [base/, specs/]
  contract: SKILL.md must be present and valid
  validation: validate-skill.sh {dir}/SKILL.md

derived-skill:
  directories: [manual/, public/, theme/]
  contract: inherits from parent skill context
  validation: parent-skill must be resolvable

forbidden-skill:
  directories: [docs/, growth/, organisation/, library/]
  contract: no operator-manual-wiring skills here
  validation: skill-file-present → BLOCK

6. Skill Execution Matrix6. Skill Execution Matrix

Welche Evidence-Klasse + Proficiency-Stufe werden für welche Operator-Operationen benötigt?

7. Registry-Operationen7. Registry Operations

Vier kanonische Abfrage-Operationen gegen das Skill-Registry:

Beispiel: Actor-Skill-Check YAMLExample: Actor Skill Check YAML

# check_actor_has_skill
request:
  actor_id: agent-copilot-001
  skill_id: skill-meta-operator-manual-wiring
  min_level: practitioner

response:
  result: true
  evidence_class: workspace_verified
  evidence:
    - type: artifact_sample
      id: ev-manual-wiring-001
      link: iio/manual/layer-architecture.html
      verified_at: 2024-01-20T14:00:00Z
      verified_by: operator-alice
  proficiency_verified: practitioner
  operator_reliance_policy: can rely with review

8. SKILL.md Vertragsregeln (base/)8. SKILL.md Contract Rules (base/)

Jede SKILL.md-Datei in einem required-skill-Verzeichnis muss diese Felder enthalten:

Bekannte SKILL.md Dateien (base/)Known SKILL.md Files (base/)

9. Skill-Konflikte & Prerequisites9. Skill Conflicts & Prerequisites

Skills können miteinander inkompatibel sein (conflicts_with) oder aufeinander aufbauen (prerequisites).

Konflikt-Prüfung erfolgt bei register_new_skill und bei check_actor_has_skill. Hat ein Actor gleichzeitig kollidierendes Skill-Paar → Role-Assignment BLOCK.

Conflict-Resolution-FlussConflict Resolution Flow

1. register_new_skill(skill-X) aufgerufen
2. Prüfe: conflicts_with enthält skill-Y?
3a. Actor hat skill-Y? → BLOCK registration (oder WARN je nach policy)
3b. Actor hat skill-Y nicht? → OK, proceed
4. Prüfe: prerequisites alle present?
5a. Fehlende prerequisites → BLOCK (fail-closed)
5b. Alle vorhanden → registration committed

10. Parameter- und Variablenmodell (operator-ready)10. Parameter and Variable Model (operator-ready)

Alle Skill-Operationen arbeiten auf einem deterministischen Variablenraum. Damit bleiben Dispatch, Gate-Entscheidungen und Audit reproduzierbar.

Parameter-Formeln (Berechnungsregeln)Parameter Formulas (Calculation Rules)

reliance_ok = (evidence_class >= min_evidence_class) AND (proficiency >= min_proficiency)

decision =
  BLOCK     if reliance_ok = false
  ESCALATE  if hitl_required = true AND human_approval = false
  GO        otherwise

11. Ablauf-Engine: Skill Dispatch State Machine11. Execution Engine: Skill Dispatch State Machine

stateDiagram-v2
  [*] --> Intake
  Intake --> ResolveRole: role_id vorhanden
  Intake --> Blocked: role_id fehlt

  ResolveRole --> ResolveSkill: role match found
  ResolveRole --> Escalate: role ambiguous

  ResolveSkill --> CheckEvidence: skill present
  ResolveSkill --> Blocked: skill missing

  CheckEvidence --> CheckProficiency: evidence >= minimum
  CheckEvidence --> Blocked: evidence too weak

  CheckProficiency --> HITLGate: proficiency >= minimum
  CheckProficiency --> Blocked: proficiency too low

  HITLGate --> Approved: hitl not required
  HITLGate --> Approved: human approved
  HITLGate --> Escalate: waiting human
  HITLGate --> Blocked: human rejected

  Approved --> CommitTX
  CommitTX --> AuditTrail
  AuditTrail --> [*]

  Escalate --> [*]
  Blocked --> [*]

12. Sequenzfluss: Actor → Registry → Gate → Audit12. Sequence Flow: Actor → Registry → Gate → Audit

sequenceDiagram
  participant A as Actor
  participant R as Skill Registry
  participant G as Gate Engine
  participant H as HITL Reviewer
  participant T as TX Log
  participant U as Audit

  A->>R: check_actor_has_skill(actor_id, skill_id, min_level)
  R-->>A: skill result + evidence_class + proficiency
  A->>G: evaluate(operation_id, risk_tier, hitl_required)
  G->>G: policy rules (fail-closed)
  alt hitl_required = true
    G->>H: request approval
    H-->>G: approve / reject
  end
  alt decision = GO
    G->>T: write tx_id + payload hash
    T->>U: append evidence links
    U-->>A: execution complete
  else decision = BLOCK
    G-->>A: blocked + reason
  else decision = ESCALATE
    G-->>A: escalated + pending owner
  end

13. Fail-Closed Entscheidungsgraph (kompakt)13. Fail-Closed Decision Graph (compact)

flowchart TD
  I[Intake: operation + actor + role + skill] --> R{Role valid?}
  R -- No --> B1[BLOCK: role mismatch]
  R -- Yes --> S{Skill present?}
  S -- No --> B2[BLOCK: missing skill]
  S -- Yes --> E{Evidence >= min?}
  E -- No --> B3[BLOCK: weak evidence]
  E -- Yes --> P{Proficiency >= min?}
  P -- No --> B4[BLOCK: low proficiency]
  P -- Yes --> H{HITL required?}
  H -- No --> G[GO]
  H -- Yes --> A{Human approved?}
  A -- No --> X[ESCALATE or BLOCK]
  A -- Yes --> G
  G --> T[TX write + Audit append]

14. Operations-Templates mit Parametern14. Operation Templates with Parameters

Template A: check_actor_has_skill

request:
  actor_id: "agent-copilot-001"
  role_id: "reviewer"
  skill_id: "skill-meta-operator-manual-wiring"
  min_evidence_class: "workspace_verified"
  min_proficiency: "practitioner"
  gate_mode: "strict"

response:
  result: true
  evidence_class: "workspace_verified"
  proficiency_verified: "practitioner"
  reliance_ok: true
  decision_hint: "GO"

Template B: dispatch_operation

request:
  operation_id: "publish_revision"
  actor_id: "operator-main"
  required_skills:
    - "skill-meta-revision-wiring"
  risk_tier: "high"
  hitl_required: true
  evidence_links:
    - "iio/public/revisions/rev-2026-04-28.json"

response:
  selected_actor: "operator-main"
  decision: "ESCALATE"
  reason: "human_owner_signoff missing"
  next_action: "request approval from registered owner"

15. Visual KPI-Board fuer Skill Governance15. Visual KPI Board for Skill Governance

xychart-beta
  title "Skill Governance KPI Trend"
  x-axis [W1, W2, W3, W4, W5]
  y-axis "Ratio" 0 --> 1
  line [0.62, 0.68, 0.74, 0.79, 0.83]
  line [0.41, 0.39, 0.35, 0.30, 0.24]

InterpretationInterpretation

1. Linie 1: Coverage/Verifikation steigt -> Reifegrad nimmt zu.
2. Linie 2: Block-Rate faellt -> weniger unzureichende Skill-Claims.
3. Bei gegenlaeufigem Trend muss Gate-Policy erneut kalibriert werden.