# Security Considerations When Defining New Skills in Knowledge-Work-Plugins

> Learn security considerations for defining new skills in knowledge-work-plugins. Discover how to implement least-privilege, user approval, and secure secret handling.

- Repository: [Anthropic/knowledge-work-plugins](https://github.com/anthropics/knowledge-work-plugins)
- Tags: best-practices
- Published: 2026-05-25

---

**Every new skill in the anthropics/knowledge-work-plugins repository must implement least-privilege integrations, explicit user approval gates for destructive actions, and secure secret handling via environment variables to pass the automated validation in [`package_data_skill.py`](https://github.com/anthropics/knowledge-work-plugins/blob/main/package_data_skill.py).**

When contributing to the **anthropics/knowledge-work-plugins** repository, understanding the **security considerations when defining new skills** is essential for safe deployment. Each skill consists of a [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) manifest and implementation code that must adhere to strict architectural guidelines enforced by the packaging system. The repository establishes patterns across existing skills like Ticket-Deflector and Zoom-Apps-SDK that demonstrate how to minimize attack surfaces while maintaining functionality.

## Core Security Architecture

The repository embeds security requirements directly into skill manifests and validates them at build time. Below are the architectural pillars enforced across the codebase.

### Least-Privilege Integration Lists

Skills must declare only the external services they truly require in the YAML front-matter of their [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) manifest. This reduces the attack surface and prevents accidental credential leakage to unnecessary systems.

The *Ticket-Deflector* skill ([`small-business/skills/ticket-deflector/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/small-business/skills/ticket-deflector/SKILL.md)) demonstrates this pattern by listing its required and optional integrations in the header section. When the validation script processes the skill, it verifies that no undeclared network dependencies exist in the implementation code.

### Explicit Approval Gates for Privileged Actions

Any action that mutates an external system—such as issuing a refund, sending an email, or deleting data—must be gated behind a user-confirmed prompt. This prevents the skill from performing destructive operations without human consent.

In the *Ticket-Deflector* workflow, the manifest describes two distinct approval steps: draft approval and refund confirmation. The skill implementation must halt execution and wait for an explicit "yes" response before proceeding with the privileged operation.

### Secure Handling of Secrets

API keys, tokens, and certificates must never be stored in the skill folder or committed to version control. Instead, skills must read sensitive values from environment variables or a secure secret store at runtime.

The *Create-Cowork-Plugin* skill ([`cowork-plugin-management/skills/create-cowork-plugin/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/cowork-plugin-management/skills/create-cowork-plugin/SKILL.md)) explicitly documents this requirement, noting that credentials should be injected via environment variables. This ensures that when the skill is packaged into a `.skill` zip archive, no secrets are accidentally included in the distribution.

### HTTPS-Only Network Calls and Response Hardening

All outbound calls to third-party APIs must use TLS to guarantee confidentiality and integrity of data in transit. Additionally, skills that serve HTTP responses must include standard security headers to protect against click-jacking, XSS, and other web attacks.

The *Zoom-Apps-SDK* skill ([`partner-built/zoom-plugin/skills/zoom-apps-sdk/concepts/security.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/partner-built/zoom-plugin/skills/zoom-apps-sdk/concepts/security.md)) defines required HTTP headers including `Content-Security-Policy`, `X-Frame-Options`, and `X-Content-Type-Options`. The skill's manifest references this security concept file, ensuring that any web-exposed endpoints follow OWASP-style response hardening guidelines.

### Input Validation and Data Privacy

Skills must treat all data from users or external services as untrusted. Validate formats, lengths, and types before processing to stop injection attacks. Furthermore, skills should not retain personally-identifiable information longer than necessary, and must encrypt any data at rest.

The *Code-Review* skill ([`engineering/skills/code-review/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/engineering/skills/code-review/SKILL.md)) includes a mandatory "Security audit (OWASP top 10, injection, auth)" step in its description workflow. For privacy compliance, the *Legal/Compliance-Check* skill ([`legal/skills/compliance-check/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/legal/skills/compliance-check/SKILL.md)) provides checklist items for "Appropriate technical and organisational measures" aligned with GDPR and CCPA requirements.

## Manifest Structure and Validation

Every skill requires a [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) manifest that serves as the single source of truth for security requirements. The packaging system enforces these contracts automatically.

### SKILL.md Requirements

A valid skill manifest must contain:
- A YAML front-matter block declaring `name`, `description`, and `compatibility` (including required integrations)
- A "Workflow" section isolating privileged actions behind user approval steps
- Optional [`concepts/security.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/concepts/security.md) file for web-exposed skills detailing HTTP headers and CSP settings

### Automated Validation with package_data_skill.py

The root-level [`package_data_skill.py`](https://github.com/anthropics/knowledge-work-plugins/blob/main/package_data_skill.py) script acts as the security gatekeeper. It validates skill folder structure and aborts packaging if it detects:
- Missing [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) manifests
- Hard-coded secrets or API keys in source files
- Undeclared network dependencies

The script ensures that every `.skill` archive has passed a baseline security checklist before distribution.

## Implementing Secure Skills

Below is a minimal skeleton incorporating the security considerations above. This example implements a "Data-Fetcher" skill that reads from a protected API over TLS using environment variables for authentication.

```yaml
---
name: data-fetcher
description: |
  Retrieves confidential data from a protected API, processes it,
  and returns a concise summary. The skill never writes data
  back to the source without explicit user consent.
compatibility: "Requires HTTPS API, optional: Slack."
---

# Data-Fetcher

## Quick start

1. User provides the identifier to fetch.
2. Skill calls the external API over TLS using a token read from an environment variable.
3. Skill returns a summary.
4. If the user requests a write-back, the skill asks for explicit confirmation.

## Security

- **Least-privilege** – only the `https://api.example.com` endpoint is listed.
- **Approval gate** – any POST/PUT request requires a "yes" reply from the user.
- **Secret handling** – the API token is read from `API_TOKEN` at runtime; never stored in the skill folder.
- **OWASP headers** – if the skill serves a web UI, include `Content-Security-Policy`, `X-Content-Type-Options`, and `X-Frame-Options`.

```

The implementation follows the manifest constraints:

```python
import os
import requests

API_URL = "https://api.example.com/data"
TOKEN = os.getenv("API_TOKEN")   # ← secret from env

def fetch(identifier: str) -> str:
    resp = requests.get(
        f"{API_URL}/{identifier}",
        headers={"Authorization": f"Bearer {TOKEN}"}
    )
    resp.raise_for_status()
    # sanitise response before use

    data = resp.json()
    # ...process data safely...

    return f"Summary: {data.get('summary', 'none')}"

```

The *Testing-Strategy* skill ([`engineering/skills/testing-strategy/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/engineering/skills/testing-strategy/SKILL.md)) recommends adding automated tests that verify these security constraints, ensuring that future changes do not unintentionally weaken the skill's security posture.

## Summary

- **Least-privilege declarations**: List only required integrations in [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) YAML front-matter to minimize attack surface.
- **Approval gates**: Gate all destructive operations behind explicit user confirmation prompts.
- **Environment-based secrets**: Store credentials in environment variables, never in the skill folder or code.
- **TLS and headers**: Use HTTPS for all outbound calls and implement OWASP security headers for web endpoints.
- **Validation enforcement**: The [`package_data_skill.py`](https://github.com/anthropics/knowledge-work-plugins/blob/main/package_data_skill.py) script blocks packaging if security requirements are violated.
- **Input sanitization**: Treat all external input as untrusted and validate before processing.

## Frequently Asked Questions

### What happens if I accidentally commit API keys to my skill folder?

The [`package_data_skill.py`](https://github.com/anthropics/knowledge-work-plugins/blob/main/package_data_skill.py) validation script scans for hard-coded secrets and aborts the packaging process if detected. Additionally, committed credentials in the Git history require immediate rotation and removal following the repository's security incident procedures.

### How does the validation script verify that my skill follows security guidelines?

[`package_data_skill.py`](https://github.com/anthropics/knowledge-work-plugins/blob/main/package_data_skill.py) checks for the presence of [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md), parses the declared integrations against the actual network calls in your code, and scans for patterns indicating hard-coded secrets. It also verifies that web-exposed skills reference a [`concepts/security.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/concepts/security.md) file when applicable.

### Are there additional requirements for skills that serve HTTP endpoints?

Yes. Skills exposing web interfaces must implement the security patterns found in the *Zoom-Apps-SDK* skill, including mandatory TLS, Content-Security-Policy headers, X-Frame-Options, and X-Content-Type-Options. These requirements are documented in the skill's [`concepts/security.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/concepts/security.md) file.

### How should I structure user confirmation for destructive operations?

Document the approval steps explicitly in the [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) "Workflow" section, then implement the confirmation logic in your code to halt execution and wait for user input before proceeding. The *Ticket-Deflector* skill provides the reference implementation for this pattern, using distinct draft approval and final confirmation stages.