Skills Integration Guide

PCL Standard Library v2.0.0

Complete guide for integrating and using skills from the PCL Standard Library in your AI personas.

Overview
Quick Start
Loading Skills
Skill Composition Patterns
Governance Integration
Tool Permissions
Performance Optimization
Best Practices
Troubleshooting

Overview

The PCL Standard Library provides 173 expert-level skills across 14 categories. Skills are modular, composable, and governance-aware units of AI capability.

What is a Skill?

A skill is a structured knowledge module that provides:

Expert domain knowledge (250-800+ lines of documentation)
Code examples (10-30+ practical examples)
Best practices and anti-patterns
YAML metadata for discovery and governance
Tool permissions defining allowed operations

Skill Categories

languages/       - 22 programming languages (Python, TypeScript, Rust, etc.)
frameworks/      - 21 frameworks (React, Spring Boot, Django, etc.)
data/            - 14 data technologies (PostgreSQL, Kafka, Snowflake, etc.)
devops/          - 17 DevOps tools (Kubernetes, Docker, Terraform, etc.)
cloud/           - 4 cloud platforms (AWS, Azure, GCP, Cloudflare)
integration/     - 6 integration patterns (GraphQL, REST, gRPC, etc.)
infrastructure/  - 4 infrastructure tools (Ansible, Packer, Consul, etc.)
security/        - 12 security domains (Zero Trust, Pentesting, etc.)
domains/         - 27 industry domains (Healthcare, Finance, etc.)
qa/              - 6 testing frameworks (Playwright, Cypress, etc.)
communication/   - 5 communication tools (Slack, Teams, etc.)
emerging/        - 8 emerging tech (Web3, Quantum, Robotics, etc.)
enterprise/      - 8 enterprise systems (SAP, Salesforce, etc.)
specialized/     - 19 specialized areas (Performance, API Design, etc.)

Quick Start

1. Browse Available Skills

Use the skill catalog to discover skills:

# View all skills in JSON format
cat stdlib/catalog/skill-catalog.json

# View lightweight index
cat stdlib/catalog/skill-index.json

# Or browse by category
ls stdlib/languages/
ls stdlib/frameworks/

2. Create Your First Persona

persona "MyFirstDeveloper" {
  version = "1.0.0"

  skills = [
    "stdlib/languages/python-expert",
    "stdlib/frameworks/django-expert",
    "stdlib/data/postgresql-expert"
  ]

  governance {
    risk_classification = "low"
    governance_level = "standard"
  }
}

3. Load and Use

from pcl import Persona

# Load persona with skills
dev = Persona.from_file("my-first-developer.pcl")

# Skills are automatically loaded and integrated
dev.query("Create a Django REST API for user management")

Loading Skills

Basic Skill Loading

Skills are loaded via path references in the skills array:

persona "Developer" {
  skills = [
    "stdlib/languages/typescript-expert",
    "stdlib/frameworks/react-expert"
  ]
}

Relative vs Absolute Paths

# Relative to PCL installation (recommended)
skills = ["stdlib/languages/python-expert"]

# Absolute path (for custom skills)
skills = ["/path/to/custom/skills/my-expert.md"]

# Mix of both
skills = [
  "stdlib/languages/go-expert",
  "/company/internal/banking-expert.md"
]

Conditional Loading

Load skills based on environment or configuration:

persona "EnvironmentAwareDev" {
  skills = concat(
    ["stdlib/languages/python-expert"],
    env.CLOUD_PROVIDER == "aws" ? ["stdlib/cloud/aws-expert"] : [],
    env.USE_K8S ? ["stdlib/devops/kubernetes-expert"] : []
  )
}

Skill Discovery at Runtime

Use the catalog for dynamic skill loading:

import json

# Load catalog
with open('stdlib/catalog/skill-catalog.json') as f:
    catalog = json.load(f)

# Find skills by tag
web_skills = [
    skill['path']
    for skill in catalog['skills']
    if 'web' in skill['tags']
]

# Find skills by category
security_skills = catalog['categories']['security']

Skill Composition Patterns

1. Layered Architecture Pattern

Build personas in layers from language to application:

persona "FullStackWebDev" {
  skills = [
    # Language Layer
    "stdlib/languages/typescript-expert",

    # Framework Layer
    "stdlib/frameworks/react-expert",
    "stdlib/frameworks/nextjs-expert",
    "stdlib/frameworks/nodejs-expert",

    # Data Layer
    "stdlib/data/postgresql-expert",
    "stdlib/data/redis-expert",

    # Integration Layer
    "stdlib/integration/rest-api-expert",
    "stdlib/integration/graphql-expert",

    # Infrastructure Layer
    "stdlib/devops/docker-expert",
    "stdlib/cloud/aws-expert"
  ]
}

2. Domain-First Pattern

Start with domain expertise, add technical skills:

persona "HealthcareDataEngineer" {
  skills = [
    # Domain Layer (Primary)
    "stdlib/domains/healthcare-expert",
    "stdlib/domains/hipaa-expert",

    # Technical Skills (Supporting)
    "stdlib/languages/python-expert",
    "stdlib/data/snowflake-expert",
    "stdlib/data/airflow-expert"
  ]
}

3. Microservice Specialist Pattern

Focus on a specific tech stack:

persona "JavaMicroservicesDev" {
  skills = [
    "stdlib/languages/java-expert",
    "stdlib/frameworks/spring-boot-expert",
    "stdlib/devops/kubernetes-expert",
    "stdlib/devops/istio-expert",
    "stdlib/data/kafka-expert",
    "stdlib/integration/grpc-expert"
  ]
}

4. Security-First Pattern

Security expertise across the stack:

persona "SecurityArchitect" {
  skills = [
    # Security Core
    "stdlib/security/zero-trust-expert",
    "stdlib/security/penetration-testing-expert",
    "stdlib/security/cryptography-expert",

    # Compliance
    "stdlib/security/gdpr-expert",
    "stdlib/security/soc2-expert",

    # Cloud Security
    "stdlib/cloud/aws-expert",
    "stdlib/devops/kubernetes-expert"
  ]

  governance {
    risk_classification = "critical"
    governance_level = "critical"
    separation_of_duties = true
  }
}

5. Polyglot Developer Pattern

Multiple language expertise:

persona "PolyglotDev" {
  skills = [
    # Backend Languages
    "stdlib/languages/python-expert",
    "stdlib/languages/go-expert",
    "stdlib/languages/rust-expert",

    # Frontend
    "stdlib/languages/typescript-expert",
    "stdlib/frameworks/react-expert",

    # Systems
    "stdlib/languages/c-expert"
  ]
}

Governance Integration

Risk Classification

Skills contribute to persona risk level:

persona "LowRiskDev" {
  skills = [
    "stdlib/languages/python-expert",
    "stdlib/frameworks/flask-expert"
  ]

  governance {
    risk_classification = "low"  # Read-only operations
  }
}

persona "HighRiskOps" {
  skills = [
    "stdlib/devops/kubernetes-expert",
    "stdlib/cloud/aws-expert",
    "stdlib/data/postgresql-expert"
  ]

  governance {
    risk_classification = "high"  # Infrastructure changes
    governance_level = "critical"
    audit_required = true
  }
}

Governance Levels

Level	Skills Examples	Audit Requirements
Standard	Languages, frameworks	Basic logging
High	Data access, API changes	Detailed logging + approval
Critical	Infrastructure, security	Full audit trail + dual approval

Compliance Frameworks

Map skills to compliance requirements:

persona "GDPRCompliantDev" {
  skills = [
    "stdlib/languages/python-expert",
    "stdlib/data/postgresql-expert",
    "stdlib/security/gdpr-expert"
  ]

  compliance {
    frameworks = ["GDPR", "ISO 27001"]
    data_classification = ["pii", "confidential"]
    encryption_at_rest = true
    pii_masking = true
  }

  governance {
    track_pii_access = true
    data_lineage = true
  }
}

Tool Permissions

Understanding allowed-tools

Each skill declares allowed tools in YAML frontmatter:

---
name: python-expert
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash(python:*, pip:*, pytest:*)
---

Persona Tool Allowlist

Combine tool permissions from all skills:

persona "RestrictedDev" {
  skills = [
    "stdlib/languages/python-expert",
    "stdlib/data/postgresql-expert"
  ]

  constraints {
    # Union of all skill allowed-tools
    allowed_tools = [
      "Read",
      "Write",
      "Edit",
      "Bash(python:*, pip:*, psql:*)"
    ]

    # Additional restrictions
    prohibited_tools = [
      "Bash(rm:-rf:*)",
      "Bash(DROP:*)",
      "Bash(sudo:*)"
    ]
  }
}

Tool Permission Patterns

Pattern matching for bash commands:

# Allow specific commands
"Bash(npm:install:*)"     # npm install <anything>
"Bash(git:status)"        # git status only
"Bash(docker:ps:*)"       # docker ps with any flags

# Allow command families
"Bash(kubectl:*)"         # All kubectl commands
"Bash(terraform:*)"       # All terraform commands

# Prohibit dangerous operations
"Bash(rm:-rf:*)"          # No rm -rf
"Bash(DROP:*)"            # No SQL DROP
"Bash(chmod:777:*)"       # No chmod 777

Production Safety Pattern

persona "ProductionSafeDev" {
  skills = [
    "stdlib/devops/kubernetes-expert",
    "stdlib/cloud/aws-expert"
  ]

  constraints {
    allowed_tools = [
      "Read",
      "Bash(kubectl:get:*)",
      "Bash(kubectl:describe:*)",
      "Bash(kubectl:logs:*)",
      "Bash(aws:s3:ls:*)",
      "Bash(aws:ec2:describe-*)"
    ]

    prohibited_tools = [
      "Bash(kubectl:delete:*)",
      "Bash(kubectl:apply:*)",
      "Bash(aws:ec2:terminate-*)",
      "Bash(rm:*)",
      "Write"  # No file writes in production
    ]
  }

  governance {
    environment = "production"
    read_only = true
  }
}

Performance Optimization

Skill Loading Performance

# Lazy loading (recommended for large personas)
persona = Persona.from_file("large-persona.pcl", lazy_load=True)

# Pre-load frequently used skills
persona = Persona.from_file("dev.pcl", preload=[
    "stdlib/languages/python-expert",
    "stdlib/frameworks/django-expert"
])

# Cache parsed skills
from pcl.cache import SkillCache
cache = SkillCache()
persona = Persona.from_file("dev.pcl", skill_cache=cache)

Skill Subsetting

Load only needed sections:

# Load only code examples (for reference)
skill = Skill.from_file(
    "stdlib/languages/python-expert.md",
    sections=["code_examples"]
)

# Load only best practices (for guidelines)
skill = Skill.from_file(
    "stdlib/security/zero-trust-expert.md",
    sections=["best_practices", "anti_patterns"]
)

Memory Optimization

# For memory-constrained environments
persona "LightweightDev" {
  skills = [
    "stdlib/languages/python-expert",
    "stdlib/frameworks/flask-expert"  # Lighter than Django
  ]

  optimization {
    skill_compression = true
    max_memory_mb = 512
    unload_unused_after = "10m"
  }
}

Best Practices

1. Start Small, Scale Up

# Bad: Loading everything
persona "OverloadedDev" {
  skills = [
    # 50+ skills loaded...
  ]
}

# Good: Start focused
persona "FocusedDev" {
  skills = [
    "stdlib/languages/python-expert",
    "stdlib/frameworks/django-expert",
    "stdlib/data/postgresql-expert"
  ]
}

2. Use Skill Catalog for Discovery

# Find skills by keyword
jq '.skills[] | select(.name | contains("web"))' \
  stdlib/catalog/skill-catalog.json

# Find skills by tag
jq '.skills[] | select(.tags[] | contains("api"))' \
  stdlib/catalog/skill-catalog.json

# Get all security skills
jq '.categories.security' stdlib/catalog/skill-catalog.json

3. Version Pin Critical Skills

persona "StableProduction" {
  skills = [
    "stdlib/languages/python-expert@1.0.0",
    "stdlib/frameworks/django-expert@1.0.0"
  ]

  version_policy {
    allow_minor_updates = true
    allow_major_updates = false
  }
}

4. Document Skill Rationale

persona "DocumentedDev" {
  description = "Full-stack web developer for e-commerce platform"

  skills = [
    # Frontend: React for SPA, TypeScript for type safety
    "stdlib/languages/typescript-expert",
    "stdlib/frameworks/react-expert",

    # Backend: Django for rapid development, PostgreSQL for relational data
    "stdlib/languages/python-expert",
    "stdlib/frameworks/django-expert",
    "stdlib/data/postgresql-expert",

    # DevOps: Docker for containers, AWS for hosting
    "stdlib/devops/docker-expert",
    "stdlib/cloud/aws-expert"
  ]
}

5. Test Persona Capabilities

import pytest
from pcl import Persona

def test_persona_has_required_skills():
    persona = Persona.from_file("developer.pcl")

    assert "python-expert" in persona.loaded_skills
    assert "django-expert" in persona.loaded_skills

def test_persona_tool_permissions():
    persona = Persona.from_file("developer.pcl")

    assert persona.can_use_tool("Read")
    assert persona.can_use_tool("Bash(python:*)")
    assert not persona.can_use_tool("Bash(rm:-rf:*)")

6. Implement Governance Guards

persona "GuardedDev" {
  skills = [
    "stdlib/cloud/aws-expert",
    "stdlib/devops/kubernetes-expert"
  ]

  governance {
    risk_classification = "high"

    pre_execution_checks = [
      "verify_environment",
      "check_resource_limits",
      "validate_permissions"
    ]

    post_execution_audit = [
      "log_all_changes",
      "notify_security_team",
      "create_audit_trail"
    ]
  }
}

Troubleshooting

Skill Not Found

Error: Skill 'stdlib/languages/python-expert' not found

Solution:

Check path is correct relative to PCL installation
Verify file exists: ls stdlib/languages/python-expert.md

Use catalog to find correct path:

jq '.skills[] | select(.name | contains("python"))' \
  stdlib/catalog/skill-catalog.json

Invalid YAML Frontmatter

Error: Invalid YAML in skill 'custom-expert.md'

Solution:

Validate YAML syntax: python scripts/validate-skills.py

Check required fields exist:

---
name: my-expert
version: 1.0.0
description: My custom skill
category: custom
tags: []
allowed-tools: []
---

Tool Permission Denied

Error: Tool 'Bash(kubectl:delete:*)' not allowed for persona

Solution:

Check skill allowed-tools in YAML frontmatter

Add tool to persona constraints:

constraints {
  allowed_tools = [
    "Bash(kubectl:delete:*)"
  ]
}

Verify governance level permits this tool

Memory Issues with Large Personas

Error: Out of memory loading 50 skills

Solution:

Enable lazy loading:

persona = Persona.from_file("large.pcl", lazy_load=True)

Reduce skill count
Use skill subsetting to load only needed sections

Conflicting Tool Permissions

Warning: Skill A allows 'Write', Skill B prohibits 'Write'

Solution:

Explicit override in persona:

constraints {
  allowed_tools = ["Write"]  # Explicitly allow
  # or
  prohibited_tools = ["Write"]  # Explicitly prohibit
}

Remove conflicting skill
Create custom skill variant with consistent permissions

Next Steps

Read the Persona Building Guide for advanced composition strategies
Review Governance Model for compliance integration
Explore Example Personas for real-world patterns
Browse Skill Catalog for available skills

Support

Issues: https://github.com/your-org/pcl/issues
Discussions: https://github.com/your-org/pcl/discussions
Documentation: https://pcl.dev/docs

FilesExpand file tree

SKILLS_INTEGRATION_GUIDE.md

Latest commit

History

SKILLS_INTEGRATION_GUIDE.md

File metadata and controls

Skills Integration Guide

Table of Contents

Overview

What is a Skill?

Skill Categories

Quick Start

1. Browse Available Skills

2. Create Your First Persona

3. Load and Use

Loading Skills

Basic Skill Loading

Relative vs Absolute Paths

Conditional Loading

Skill Discovery at Runtime

Skill Composition Patterns

1. Layered Architecture Pattern

2. Domain-First Pattern

3. Microservice Specialist Pattern

4. Security-First Pattern

5. Polyglot Developer Pattern

Governance Integration

Risk Classification

Governance Levels

Compliance Frameworks

Tool Permissions

Understanding allowed-tools

Persona Tool Allowlist

Tool Permission Patterns

Production Safety Pattern

Performance Optimization

Skill Loading Performance

Skill Subsetting

Memory Optimization

Best Practices

1. Start Small, Scale Up

2. Use Skill Catalog for Discovery

3. Version Pin Critical Skills

4. Document Skill Rationale

5. Test Persona Capabilities

6. Implement Governance Guards

Troubleshooting

Skill Not Found

Invalid YAML Frontmatter

Tool Permission Denied

Memory Issues with Large Personas

Conflicting Tool Permissions

Next Steps

Support