Skip to content

Architecture Proposal: Zero-Trust Skill Packages (Secure Skill Bundles)

1. Vision & Executive Summary

Traditional agent skills (such as skills.sh, Cursor rules, or raw markdown prompt guides) operate under an insecure paradigm: they provide instruction text to an agent while leaving the agent with unrestricted, root/user privileges across the filesystem, subprocesses, and the network.

ctxsec Secure Skill Bundles evolve skills from untrusted instruction text into Hermetic Capability Packages: 

Secure Skill Package = [Instruction (SKILL.md)] + [Deterministic Guardrails (ctxsec.yaml)] + [Cryptographic Signature (skill.yaml)]

When an agent invokes or activates a skill, ctxsec immediately applies the skill's declared hardware sandbox, CEL policy bounds, network whitelist, and tool gating — granting the agent only the exact least-privilege surface required to perform that skill.

2. Secure Skill Bundle Directory Layout

A canonical ctxsec skill package has the following layout:

skills/<vendor>/<skill-name>/
├── SKILL.md            # Metadata frontmatter + LLM instruction prompt & operational guide
├── ctxsec.yaml         # Deterministic policy bounds (tools, network, filesystem, tokens)
├── skill.yaml          # Cryptographic Ed25519 signature, author identity, and file digests
└── tools/              # (Optional) local scripts, MCP tools, or executable helper utilities

Specification of Components:

A. SKILL.md (Instruction Layer)

Markdown instructions formatted with YAML frontmatter: 

---
name: playwright-verifier
vendor: ctxsec
version: 1.0.0
description: Executes headless Playwright verification against web frontend services.
tags: [playwright, ui, browser, testing]
license: Apache-2.0
---

# Playwright Verifier Skill
Instructions for the agent on how to run headless verification, examine DOM, and capture screenshots.

B. ctxsec.yaml (Least-Privilege Guardrails)

Hardware sandbox and CEL microsecond policy definitions enforced before any tool execution: 

apiVersion: ctxsec.io/v1alpha1
kind: SkillBoundary
metadata:
  name: playwright-verifier
  vendor: ctxsec
  version: 1.0.0

spec:
  # Filesystem bounds: where the skill is allowed to read and write
  filesystem:
    read: [".", "/opt/homebrew/bin/playwright"]
    write: ["local/scratch", "local/verify_*.png"]
    forbidden: [".git", "~/.ssh", "~/.gnupg", "~/.aws", ".env*"]

  # Network egress filtering: socket-level firewall
  network:
    default: deny
    allow:
      - "localhost:*"
      - "127.0.0.1:*"
      - "ctxsec.io:443"
      - "gosec.io:443"

  # Tool permissions: exact callable tools
  tools:
    allowed:
      - "run_command"
      - "view_file"
      - "list_dir"
    forbidden:
      - "write_to_file"
      - "replace_file_content"

  # CEL Policy Rules (< 5µs evaluation)
  rules:
    - id: "enforce-headless-only"
      expression: "!request_command.contains('--headed')"
      action: "deny"
      message: "Browser must run strictly in headless mode."

    - id: "block-credential-access"
      expression: "!request_command.contains('cat ~/.') && !request_command.contains('export')"
      action: "deny"
      message: "Accessing host credentials from skill sandbox is forbidden."

C. skill.yaml (Cryptographic Trust)

Calculated SHA-256 digest of all files in the package, signed with the author's Ed25519 key: 

name: ctxsec/playwright-verifier
version: 1.0.0
author: ctxsec
digest: "sha256:8f4c2e...b31"
public_key: "ed25519:7a4f...e89b"
signature: "ed25519:e410...99c2"

3. Core Workspace Skills Porting Roadmap

We port our battle-tested workspace skills as the foundational reference implementations:

Skill Package Purpose Guardrail Boundary (ctxsec.yaml)
ctxsec/playwright-verifier Headless browser testing & DOM visual validation Network: localhost:*, ctxsec.io. Write: local/verify_*.png. Forbidden: code editing tools.
ctxsec/ctx-builder Hermetic Go compilation & test suites Network: default: deny. Write: bin/, local/scratch/. CEL: CGO_ENABLED=0 enforcement.
ctxsec/backlog-manager SQLite task ledger & DAG dependency scheduler Tools: Strict MCP only. Shell execution (run_command) forbidden. Write: isolated to local/backlog.sqlite.
ctxsec/feature-lifecycle 6-phase engineering lifecycle guard High token limit; strict stage transition validation.
  1. Workspace & Ecosystem Skills:
  2. Authored by us under the Apache-2.0 license. 100% clean and immediately exportable.
  3. Third-Party & Vendor Skills:
  4. No blind verbatim copying: Vendor-specific or proprietary skills from third-party tools must never be copied into the repo.
  5. Clean-Room Authoring: All new skills will be designed from scratch with original instruction text, optimized zero-allocation tools, and dedicated ctxsec.yaml guardrails.
  6. Open Source Skills: For external skills with permissive licenses (MIT/Apache), we only distribute them if full attribution and copyright notices are preserved, or provide ctxsec security policy overlays that wrap existing installed skills without redistributing third-party text.

5. Client Integration & 1-Click Installation Architecture

When a user runs: 

ctx skill install ctxsec/playwright-verifier --agent=vscode
or clicks a deep link on ctxsec.io: 1. ctx verifies the package's Ed25519 signature. 2. Installs the SKILL.md instruction into the target agent's skill directory (e.g. .agents/skills/ or ~/.gemini/antigravity/skills/). 3. Registers the ctxsec.yaml policy boundary in the agent's MCP proxy configuration (mcp-proxy), ensuring the agent is bound by the policy whenever that skill is activated.