Security Considerations for Writing PM Skills: A Complete Guide

Yes, writing PM Skills requires strict security practices including never hard-coding secrets, referencing static security audits, and documenting trust boundaries to prevent credential leakage and unauthorized access.

When authoring skills for the phuryn/pm-skills repository, understanding security considerations for writing skills is essential because these plain-text Markdown files execute in Claude-based agent environments and may be shared across teams. Each SKILL.md file auto-loads at runtime when trigger phrases appear, making it critical to avoid credential exposure and provide explicit security guidance within the documentation itself.

Never Commit Secrets to Skill Files

API keys, tokens, passwords, and private certificates must never appear in a skill file. The marketplace is public under the repository's LICENSE, meaning any embedded secret would be exposed to anyone who installs the plugin.

The repository enforces this through .env-related read-deny rules at the tooling level. When writing a skill, assume the Markdown source is world-readable and design accordingly.

Reference the Static Security Audit Workflow

Skills that manipulate user-provided data, invoke external services, or write to storage should encourage users to run the /security-audit-static command. This command maps entry points, trust boundaries, and sinks, then self-refutes any findings that cannot be substantiated.

According to the implementation in pm-ai-shipping/commands/security-audit-static.md, the audit provides a systematic, evidence-backed review of the codebase before shipping. The shipping-artifacts skill demonstrates this by building documentation that feeds the security audit workflow.

Document Trust Boundaries and Data Flows

The intent-vs-implementation gap represents a critical security concern: documenting what a system should do (e.g., required permissions, data flows) is insufficient without verifying the enforcement is actually implemented.

The skill defined in pm-ai-shipping/skills/intended-vs-implemented/SKILL.md explains this gap and provides methods for catching "permission declared but never checked" bugs. When writing your skill, explicitly state assumptions such as "requires HTTPS," "assumes authenticated user," or "does not store PII" to make the security posture testable.

Include Legal Disclaimers for Compliance Content

Any skill generating legal-type documents (privacy policies, NDAs, compliance checklists) must contain a bold disclaimer stating the output is not legal advice and requires review by a qualified attorney.

The privacy-policy skill in pm-toolkit/skills/privacy-policy/SKILL.md demonstrates this pattern with a clear disclaimer to prevent reliance on AI-generated text for compliance, which could otherwise create legal exposure.

Minimize Attack Surface with Scope-Limited Loading

Skills auto-load only when their trigger phrases appear. Overly broad trigger patterns could cause a skill to load in unrelated conversations, potentially leaking internal workflow details.

Keep the front-matter description field concise and minimal. The repository's guidelines in CLAUDE.md (line 56) enforce a "keep front-matter lean" policy to encourage minimal exposure and prevent accidental information disclosure.

Practical Implementation Examples

Secure Front-Matter Structure

Structure your SKILL.md front-matter to include security tags and clear descriptions:

---
name: example-secure-skill
description: |
  Demonstrates a skill that accesses user‑provided data.
  Requires HTTPS, authenticated request, and runs a static security audit.
---

# Example Secure Skill

The skill expects `$INPUT_DATA` from an authenticated user and stores it
in an encrypted database column.  
> **Security note** – Run `/security‑audit‑static` after implementing the
> code to verify that all sinks are protected.

This file would live at pm-toolkit/skills/example-secure-skill/SKILL.md, following the same structure as existing skills like privacy-policy.

Invoking the Security Audit

After implementing new features, invoke the audit from your terminal:

# After writing the implementation of a new feature:

claude plugin run /security-audit-static src/features/my-feature

The command respects the audit steps and high-miss checklist defined in pm-ai-shipping/commands/security-audit-static.md.

Security Checklists in Skill Bodies

Include explicit verification steps in your skill documentation:

## Security Checklist

- [ ] Verify that `$USER_ID` is validated against the JWT payload.
- [ ] Ensure all database writes use prepared statements.
- [ ] Confirm that any outbound HTTP call is whitelist‑checked.
- [ ] Run `/security‑audit‑static` and address all findings.

This mirrors the checklist approach used in pm-ai-shipping/skills/shipping-artifacts/SKILL.md, which enumerates required elements including "permissions, variables/secrets, and a test-coverage map."

Summary

• Never commit secrets: API keys and tokens must stay out of SKILL.md files; leverage .env protections and assume public visibility.
• Reference static audits: Use /security-audit-static for skills handling sensitive data, following the implementation in pm-ai-shipping/commands/security-audit-static.md.
• Close intent gaps: Document and verify the difference between intended security controls and actual implementation using the patterns in pm-ai-shipping/skills/intended-vs-implemented/SKILL.md.
• Add legal disclaimers: Include bold warnings for compliance-related outputs as shown in pm-toolkit/skills/privacy-policy/SKILL.md.
• Limit exposure: Use concise trigger patterns and lean front-matter per CLAUDE.md guidelines to prevent unintended loading.

Frequently Asked Questions

Can I store API keys directly in my skill file?

No. Hard-coding secrets in SKILL.md files exposes credentials to anyone who installs the plugin because the repository is public. The repository enforces .env-related read-deny rules to prevent this at the tooling level. Instead, reference environment variables or secure vaults, and document required secrets in the security checklist without including the values.

What is the intent-vs-implementation gap?

The intent-vs-implementation gap occurs when a skill documents security requirements (like permission checks or data validation) but the actual code fails to enforce them. This common flaw is addressed by the intended-vs-implemented skill, which provides methods to verify that declared permissions are actually checked at runtime, preventing "permission declared but never checked" vulnerabilities.

How do I run a security audit on my skill?

Invoke the /security-audit-static command against your implementation directory. According to pm-ai-shipping/commands/security-audit-static.md, this command maps entry points, trust boundaries, and sinks while self-refuting unsubstantiated findings. Skills like shipping-artifacts explicitly build documentation to feed this audit process.

Are PM Skills automatically loaded in every conversation?

No. Skills use scope-limited loading based on trigger phrases in the front-matter description. However, overly broad trigger patterns could cause unintended loading in unrelated conversations. Keep your description field concise and specific, following the "keep front-matter lean" guideline in CLAUDE.md, to minimize the attack surface and prevent accidental exposure of workflow details.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}