Files
personamanagmentlayer__pcl/stdlib/devops/devops-expert/SKILL.md
ANGX 4e07a6a874 feat(stdlib)!: Agent Skills v1.0 conformance, resolver fix, and 17 new skills (#43)
* chore(stdlib): add conformance tooling for the skills library

The library had no gate that could express what a valid skill is, so
malformed frontmatter, over-budget files and credential literals went
unnoticed. These scripts define and enforce that contract.

- validate-skills.py: extend with Agent Skills v1.0 conformance -
  naming rules and directory agreement, an explicit activation trigger
  in the description, canonical layout, the 500-line SKILL.md budget,
  relative-link integrity, and two security rules (no unrestricted
  Bash(*) grant, no credential literals). Structural checks now read a
  skill as a whole so material moved into references/ still counts.
- split-skill-references.py: move the heaviest sections of an oversized
  SKILL.md into references/. Verifies line by line that every source
  line lands in exactly one output and refuses to write otherwise.
- generate-skill-inventory.py: derive SKILLS_INVENTORY.md and
  DIRECTORY_STRUCTURE.md from the tree so they cannot drift.
- generate-skill-catalog.py: index the canonical layout only, count
  references/ toward a skill's size, and stop truncating descriptions
  at 200 characters - the catalog is the discovery surface and must
  carry the activation trigger.
- .gitignore: Python bytecode from these scripts, and local .pcl state.

Reviewed-by: Security Analyst, Compiler Engineer, DevX Engineer

* fix(stdlib): bring all 174 skills to Agent Skills v1.0 conformance

No skill in the library was conformant. 41 of 175 failed the existing
validator outright, and none satisfied the spec. This pass fixes the
tree and records the result. See stdlib/CHANGELOG.md for the per-skill
versioning and migration notes.

BREAKING CHANGE: one skill removed, five moved, seven with a capability
withdrawn. Library version 2.0.0 -> 3.0.0.

Structure
- Convert 71 skills stored as flat files to <category>/<name>/SKILL.md,
  the layout the spec requires and the only one able to carry companion
  resources.
- Rename 5 directories that disagreed with their declared name:, so
  resolution by path and by name stop giving different answers. The
  repository docs already referenced the corrected paths.
- Merge the duplicate legal-technology skills into legaltech-expert and
  delete legal-tech-expert, carrying over everything the survivor
  lacked.

Metadata
- Repair 20 unparseable frontmatters: an H1 preceded the --- block and
  the key was skill_id: instead of name:, so any parser reading
  frontmatter at offset 0 saw no metadata at all. The objectives,
  prerequisites and outcome they carried become real body sections.
- Add the missing version: to 21 skills, fold keywords into tags, move
  expertise_level under metadata, and align 10 category: values with
  their directory.

Discoverability
- Give all 174 descriptions an explicit "Use when ..." trigger, built
  from each skill's own tags and section headings. 152 previously said
  only what the skill was about, leaving an agent nothing to match on.

Progressive disclosure
- Split 127 oversized skills, moving bulk material into references/ read
  on demand and leaving an index behind. A SKILL.md now averages 277
  lines instead of 644 and none exceeds 500. Verified lossless line by
  line against the previous revision.

Security
- Withdraw the unrestricted Bash(*) grant from 7 skills; none of the six
  non-financial ones contained a single shell command. finance-expert
  documents code that charges cards and reads bank accounts, so it now
  grants no shell at all.
- Remove credential literals: Stripe keys, two JWT signing keys, an
  Express session secret, a Redis password and WiFi credentials, all
  inlined in examples. They load from the environment now.
- finance-expert: idempotency keys were documented but absent, so a
  retry double-charged; webhook signature failures were not caught, so a
  forged event raised uncaught instead of being rejected;
  int(amount * 100) truncated fractions of a cent. All fixed, plus a
  money-movement guardrails section.
- trading-expert: place_order routed without any pre-trade risk check
  although a RiskManager sat unused in the next section. Risk validation
  now runs before routing and raises rather than returning a boolean a
  caller can ignore; live routing is opt-in.
- Correct an Ansible Vault example that showed plaintext under an
  "encrypted" label.

Also fixes 8 broken documentation links and a prematurely closed code
fence in skill-creator-expert that leaked template content into prose.

Per the repository file-organization policy, four stale progress reports
(SKILLS_MANIFEST, COMPLETE_SKILLS_LIBRARY, COMPLETE_LIBRARY_MANIFEST,
PHASE_3_DATA_ANALYTICS) move out of stdlib/ into the gitignored
.roadmap/status/stdlib/; they claimed 31 of 100 skills complete. They
appear here as deletions because .roadmap/ is not tracked.

Reviewed-by: Security Analyst, Language Designer, DevX Engineer,
             Documentation Specialist

* fix(skills): resolve standard library skills from their real layout

No stdlib skill was resolvable. SkillResolver looked for
`<stdlibDir>/<name>.md` with stdlibDir defaulting to `stdlib/skills`, a
directory that does not exist, and the path ignored the category level
the library actually uses. The two LSP providers had the same wrong
directory and scanned only one level deep, so neither completion nor
go-to-definition could see a skill either.

- skill-discovery.ts: enumerate skill entry points across the shapes in
  use - a flat `<name>.md`, `<name>/SKILL.md`, and
  `<category>/<name>/SKILL.md` - while skipping references/, scripts/
  and assets/, which hold supporting material rather than entry points.
- skill-resolver.ts: point stdlibDir at `stdlib`, and look the name up
  as a directory under any category as well as the two legacy shapes, so
  existing custom stdlib directories keep working. The name is used as a
  single path segment and rejected if it contains a separator or
  traversal, so a reference cannot escape the stdlib root.
- Rewire both LSP providers onto the shared discovery helper.

Tests: 13 new cases covering the layouts, ordering, the references/
exclusion, path-traversal rejection, and an integration test that
resolves real shipped skills by bare name.

Reviewed-by: Compiler Engineer, Runtime Architect, Security Analyst

* feat(stdlib): add 17 skills covering the library's largest gaps

Selection was driven by cross-referencing coverage against observed usage
rather than by intuition: Stack Overflow and GitHub Octoverse data for
which technologies matter, and install rankings on public agent-skill
registries for the shape of skills people actually use.

That comparison found a mismatch of form, not only of coverage. The
most-installed skills in the ecosystem are procedures - tdd, refactoring,
frontend design, browser automation - while all 174 existing skills were
domain knowledge shaped as <domain>-expert. The new workflows/ category
closes that gap and introduces the <activity>-workflow convention.

New category workflows/ (4)
- tdd-workflow, refactoring-workflow, debugging-workflow,
  code-review-workflow. code-review-workflow complements rather than
  replaces code-review-expert: procedure versus judgement. Merge them if
  the split proves confusing in use.

Applied AI (3) - the largest coverage gap
- llm-engineering-expert, rag-expert, agent-engineering-expert.
  The library referenced LLMs in tags but covered none of it: pgvector
  appeared zero times across 174 skills, LangChain once, MCP twice
  despite the repository shipping an MCP integration guide.

Capabilities (2)
- document-processing-expert (PDF, DOCX, XLSX, PPTX in one skill),
  browser-automation-expert (a client against third-party sites,
  distinct from playwright-expert which tests your own application).

Data (3)
- mysql-expert, the second most used database and previously absent
  while rarer stores had skills; analytical-databases-expert;
  stream-processing-expert.

Security (3)
- secrets-management-expert, supply-chain-security-expert (OWASP A03
  2025), identity-access-expert (OWASP A01).

Interface and meta (2)
- accessibility-expert: design/ held only design-expert, which despite
  its name covers software architecture, so WCAG had no home.
- skill-router: find and compose skills across 191, with a
  disambiguation table for overlapping pairs.

Grouping by decision context rather than by technology keeps the growth
to 17 skills for roughly 50 topics. Five vector stores live inside
rag-expert; four document formats inside document-processing-expert.
Per-tool depth sits in references/, which the progressive-disclosure work
in 3.0.0 made cheap.

Four further gaps are better served by extending existing skills -
PyTorch and TensorFlow in ml-expert, OpenTelemetry in monitoring-expert,
Pulumi and Crossplane in terraform-expert - and are not in this change.

Library 3.0.0 -> 3.1.0, additive only. Adds the workflows label to the
inventory generator; catalogue, inventory, structure and CHANGELOG
regenerated.

Reviewed-by: Product Strategist, Security Analyst, DevX Engineer,
             Documentation Specialist

* fix(test): create test directories with mkdtempSync

CodeQL flagged js/insecure-temporary-file (CWE-377) on both suites.
`join(tmpdir(), <predictable name>)` followed by mkdirSync creates a
world-readable directory at a guessable path, so another local user can
pre-create it or plant a symlink between the name being computed and the
directory being created.

mkdtempSync creates the directory atomically with a random suffix and
0700 permissions, which closes both the disclosure and the race.

One occurrence is new in this branch (skill-discovery); the other
pre-dates it in skill-resolver and is fixed in the same pass rather than
left as a known finding in a file this branch already touches.
2026-09-05 04:35:30 +02:00

13 KiB

name, version, description, category, tags, allowed-tools
name version description category tags allowed-tools
devops-expert 2.0.0 Expert-level DevOps practices, culture, automation, and continuous delivery. Use when the user mentions CI/CD, automation, infrastructure, or culture, or when the task involves DevOps Culture or Culture & Process. devops
devops
ci-cd
automation
infrastructure
culture
Read
Write
Edit
Bash(python:*, python3:*, pip:*, pytest:*)

DevOps Expert

Expert guidance for DevOps practices, culture, CI/CD pipelines, infrastructure automation, and operational excellence.

Core Concepts

DevOps Culture

  • Collaboration and communication
  • Shared responsibility
  • Continuous improvement
  • Breaking down silos
  • Blameless culture
  • Measuring everything

Automation

  • Infrastructure as Code (IaC)
  • Configuration management
  • Deployment automation
  • Testing automation
  • Monitoring automation
  • Self-service platforms

CI/CD

  • Continuous Integration
  • Continuous Delivery
  • Continuous Deployment
  • Pipeline as Code
  • Artifact management
  • Release strategies

CI/CD Pipeline

# GitHub Actions Example
name: CI/CD Pipeline

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run linting
        run: npm run lint

      - name: Run tests
        run: npm test

      - name: Run security scan
        run: npm audit

      - name: Upload coverage
        uses: codecov/codecov-action@v3

  build:
    needs: test
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - uses: actions/checkout@v3

      - name: Log in to Container Registry
        uses: docker/login-action@v2
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v4
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}

      - name: Build and push Docker image
        uses: docker/build-push-action@v4
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

  deploy-staging:
    needs: build
    if: github.ref == 'refs/heads/develop'
    runs-on: ubuntu-latest
    environment: staging

    steps:
      - name: Deploy to staging
        run: |
          kubectl set image deployment/myapp \
            myapp=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }} \
            --namespace=staging

      - name: Wait for rollout
        run: kubectl rollout status deployment/myapp -n staging

      - name: Run smoke tests
        run: npm run test:smoke

  deploy-production:
    needs: build
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment: production

    steps:
      - name: Deploy to production
        run: |
          kubectl set image deployment/myapp \
            myapp=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }} \
            --namespace=production

      - name: Wait for rollout
        run: kubectl rollout status deployment/myapp -n production

Infrastructure as Code

# Pulumi Infrastructure as Code
import pulumi
import pulumi_aws as aws

# VPC
vpc = aws.ec2.Vpc("main-vpc",
    cidr_block="10.0.0.0/16",
    enable_dns_hostnames=True,
    enable_dns_support=True,
    tags={"Name": "main-vpc"})

# Subnets
public_subnet = aws.ec2.Subnet("public-subnet",
    vpc_id=vpc.id,
    cidr_block="10.0.1.0/24",
    availability_zone="us-east-1a",
    map_public_ip_on_launch=True,
    tags={"Name": "public-subnet"})

private_subnet = aws.ec2.Subnet("private-subnet",
    vpc_id=vpc.id,
    cidr_block="10.0.2.0/24",
    availability_zone="us-east-1b",
    tags={"Name": "private-subnet"})

# Internet Gateway
igw = aws.ec2.InternetGateway("igw",
    vpc_id=vpc.id,
    tags={"Name": "main-igw"})

# Route Table
route_table = aws.ec2.RouteTable("public-rt",
    vpc_id=vpc.id,
    routes=[
        aws.ec2.RouteTableRouteArgs(
            cidr_block="0.0.0.0/0",
            gateway_id=igw.id,
        )
    ],
    tags={"Name": "public-rt"})

# Security Group
security_group = aws.ec2.SecurityGroup("web-sg",
    vpc_id=vpc.id,
    description="Allow HTTP and HTTPS traffic",
    ingress=[
        aws.ec2.SecurityGroupIngressArgs(
            protocol="tcp",
            from_port=80,
            to_port=80,
            cidr_blocks=["0.0.0.0/0"],
        ),
        aws.ec2.SecurityGroupIngressArgs(
            protocol="tcp",
            from_port=443,
            to_port=443,
            cidr_blocks=["0.0.0.0/0"],
        ),
    ],
    egress=[
        aws.ec2.SecurityGroupEgressArgs(
            protocol="-1",
            from_port=0,
            to_port=0,
            cidr_blocks=["0.0.0.0/0"],
        )
    ])

# EKS Cluster
cluster = aws.eks.Cluster("app-cluster",
    role_arn=cluster_role.arn,
    vpc_config=aws.eks.ClusterVpcConfigArgs(
        subnet_ids=[public_subnet.id, private_subnet.id],
        security_group_ids=[security_group.id],
    ))

# Export outputs
pulumi.export("vpc_id", vpc.id)
pulumi.export("cluster_name", cluster.name)
pulumi.export("cluster_endpoint", cluster.endpoint)

Deployment Strategies

from typing import List, Dict
import time

class DeploymentStrategy:
    """Implement various deployment strategies"""

    def __init__(self, service_name: str):
        self.service_name = service_name

    def blue_green_deployment(self, blue_version: str, green_version: str):
        """Blue-Green deployment"""
        # Deploy green environment
        self.deploy_environment("green", green_version)

        # Run tests on green
        if self.run_tests("green"):
            # Switch traffic to green
            self.switch_traffic("green")

            # Keep blue for rollback
            print(f"Deployment successful. Blue ({blue_version}) kept for rollback.")
        else:
            # Rollback - keep blue active
            print("Tests failed on green. Keeping blue active.")

    def canary_deployment(self, current_version: str, new_version: str,
                         canary_percentage: int = 10):
        """Canary deployment"""
        # Deploy canary with small percentage
        self.deploy_canary(new_version, canary_percentage)

        # Monitor metrics
        metrics = self.monitor_canary_metrics(duration_minutes=10)

        if metrics['error_rate'] < 0.1 and metrics['latency_p95'] < 500:
            # Gradually increase canary traffic
            for percentage in [25, 50, 75, 100]:
                self.update_canary_traffic(percentage)
                time.sleep(300)  # 5 minutes between increases

                if not self.check_health():
                    self.rollback(current_version)
                    return False

            print(f"Canary deployment successful: {new_version}")
            return True
        else:
            self.rollback(current_version)
            print("Canary deployment failed - rolled back")
            return False

    def rolling_deployment(self, version: str, batch_size: int = 1):
        """Rolling deployment"""
        instances = self.get_instances()

        for i in range(0, len(instances), batch_size):
            batch = instances[i:i + batch_size]

            # Update batch
            for instance in batch:
                self.update_instance(instance, version)
                self.wait_for_healthy(instance)

            # Verify batch health
            if not self.check_health():
                print(f"Rolling deployment failed at batch {i//batch_size + 1}")
                return False

        print(f"Rolling deployment successful: {version}")
        return True

    def feature_flag_deployment(self, feature_name: str, enabled: bool,
                               rollout_percentage: int = 100):
        """Feature flag based deployment"""
        return {
            'feature': feature_name,
            'enabled': enabled,
            'rollout_percentage': rollout_percentage,
            'targeting': {
                'user_segments': ['beta_users'] if rollout_percentage < 100 else ['all']
            }
        }

Configuration Management

from typing import Dict, Any
import yaml
import json

class ConfigurationManager:
    """Manage application configuration"""

    def __init__(self, environment: str):
        self.environment = environment
        self.config = {}

    def load_config(self, config_file: str):
        """Load configuration from file"""
        with open(config_file, 'r') as f:
            if config_file.endswith('.yaml') or config_file.endswith('.yml'):
                self.config = yaml.safe_load(f)
            elif config_file.endswith('.json'):
                self.config = json.load(f)

    def get(self, key: str, default: Any = None) -> Any:
        """Get configuration value"""
        keys = key.split('.')
        value = self.config

        for k in keys:
            if isinstance(value, dict):
                value = value.get(k)
            else:
                return default

            if value is None:
                return default

        return value

    def merge_environment_config(self, env_config: Dict):
        """Merge environment-specific configuration"""
        self.config = self._deep_merge(self.config, env_config)

    def _deep_merge(self, base: Dict, override: Dict) -> Dict:
        """Deep merge two dictionaries"""
        result = base.copy()

        for key, value in override.items():
            if key in result and isinstance(result[key], dict) and isinstance(value, dict):
                result[key] = self._deep_merge(result[key], value)
            else:
                result[key] = value

        return result

    def validate_required_keys(self, required_keys: List[str]) -> List[str]:
        """Validate that required configuration keys exist"""
        missing = []

        for key in required_keys:
            if self.get(key) is None:
                missing.append(key)

        return missing

Monitoring and Observability

import logging
from opencensus.ext.azure import metrics_exporter
from opencensus.stats import aggregation as aggregation_module
from opencensus.stats import measure as measure_module
from opencensus.stats import stats as stats_module
from opencensus.stats import view as view_module
from opencensus.tags import tag_map as tag_map_module

class ObservabilityStack:
    """Implement observability best practices"""

    def __init__(self):
        self.logger = self._setup_logging()
        self.stats = stats_module.stats
        self.view_manager = self.stats.view_manager

    def _setup_logging(self) -> logging.Logger:
        """Setup structured logging"""
        logger = logging.getLogger(__name__)
        handler = logging.StreamHandler()

        formatter = logging.Formatter(
            '{"time": "%(asctime)s", "level": "%(levelname)s", '
            '"service": "%(name)s", "message": "%(message)s"}'
        )
        handler.setFormatter(formatter)
        logger.addHandler(handler)
        logger.setLevel(logging.INFO)

        return logger

    def log_with_context(self, level: str, message: str, **context):
        """Log with additional context"""
        log_func = getattr(self.logger, level)
        log_func(message, extra=context)

    def track_custom_metric(self, metric_name: str, value: float,
                           tags: Dict[str, str]):
        """Track custom application metric"""
        # Implementation would send to metrics backend
        pass

    def create_distributed_trace(self, operation_name: str):
        """Create distributed trace span"""
        # Implementation would use OpenTelemetry or similar
        pass

Best Practices

Culture & Process

  • Foster collaboration between Dev and Ops
  • Automate everything possible
  • Measure and monitor continuously
  • Practice blameless post-mortems
  • Share knowledge and documentation
  • Encourage experimentation
  • Celebrate successes and learn from failures

CI/CD

  • Keep builds fast (<10 minutes)
  • Run tests in parallel
  • Use pipeline as code
  • Implement automated rollbacks
  • Require code review before merge
  • Use trunk-based development
  • Deploy small, frequent changes

Infrastructure

  • Use Infrastructure as Code
  • Version everything (code, config, infrastructure)
  • Implement disaster recovery
  • Practice chaos engineering
  • Use immutable infrastructure
  • Automate security scanning
  • Monitor cloud costs

Anti-Patterns

❌ Manual deployments ❌ Configuration drift ❌ No automated testing ❌ Long-lived feature branches ❌ Blame culture ❌ Siloed teams ❌ Ignoring technical debt

Resources