# Security Considerations for Writing PM Skills: A Complete Guide > Learn essential security practices for writing PM skills. Prevent credential leakage by avoiding hardcoded secrets and documenting trust boundaries. A complete guide from phuryn/pm-skills. - Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills) - Tags: best-practices - Published: 2026-06-28 --- **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`](https://github.com/phuryn/pm-skills/blob/main/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](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) front-matter to include security tags and clear descriptions: ```markdown --- 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`](https://github.com/phuryn/pm-skills/blob/main/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: ```bash # 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`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/security-audit-static.md). ### Security Checklists in Skill Bodies Include explicit verification steps in your skill documentation: ```markdown ## 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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/privacy-policy/SKILL.md). - **Limit exposure**: Use concise trigger patterns and lean front-matter per [`CLAUDE.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md), to minimize the attack surface and prevent accidental exposure of workflow details.