Write and Maintain Product Management Skills That Teach Good Judgment

## Keep the reasons and examples that teach the user good judgment ### Serve the dual audience A product-management skill should help a practitioner complete useful work and become better at the craft. Design every skill for both the human building judgment and the agent executing the workflow. Do not optimize for one audience at the expense of the other. Make the reasoning behind the workflow visible enough that recommendations are trustworthy, explainable, and transferable. The user should understand why an approach works, not merely receive a finished artifact. ### Protect the learning structure - Do not shorten explanations when doing so removes the reasoning needed to make sound decisions. - Preserve explicit anti-patterns because they teach users what to recognize and avoid in real situations. - Use examples that show the reasoning process, not only the final output. - Define specialized terms when they first appear and make trade-offs explicit. - Keep the workflow practical and agent-ready without stripping away the coaching layer. When improving efficiency, remove repetition, filler, and incidental background before removing lessons, examples, or failure modes. If it is unclear whether a passage is scaffolding or clutter, retain it until its function is understood. ### Demonstrate quality across contexts Include at least one concrete example that shows how evidence leads to a decision. For a fully developed skill, add a reusable template and worked examples from two meaningfully different business settings, such as a software service and a physical or operational business. Use fictional organizations and data. ## Give each skill its own folder and never hand-edit generated lists ### Separate canonical sources from derived outputs Keep each skill in its own consistently named folder with one canonical skill document and any skill-specific supporting assets or scripts. Store reusable orchestration commands separately from individual skills. Maintain research, user documentation, preview applications, and release artifacts in distinct areas with clear ownership. Treat generated catalogs, indexes, package copies, and distribution bundles as derived artifacts. Regenerate them from canonical sources instead of editing them directly. Use lowercase kebab-case for skill folder names and keep the folder name synchronized with the skill's declared name. Preserve stable paths whenever possible; rename a skill only when necessary, then update every reference. ### Follow ownership boundaries Confirm which repository or workspace owns the content before editing it. A shared library, a product-specific playbook, and a distribution repository may refer to one another while having different sources of truth. Work in the owning location and treat other locations as read-only references unless the task explicitly changes that boundary. Do not infer structure from a familiar directory name alone. Use the repository's own definitions, contribution rules, scripts, and existing examples before making structural decisions. ### Find the most specific capability Before improvising product-management guidance, inspect the available skills and choose the most specific match. Common domains include discovery, Jobs to Be Done, personas, product strategy, prioritization, roadmaps, requirements documents, user stories, acceptance criteria, artificial-intelligence product work, agent workflows, and stakeholder alignment. Treat these as coaching and artifact-generation workflows rather than generic software-engineering tasks. ## Include examples and common mistakes in each skill and ask one question at a time ### Use a consistent document contract Give each skill a clear sequence such as Purpose, Input, Key Concepts, Application, Examples, Common Pitfalls, and References. Include frontmatter fields for name, description, and type. Keep the name within 64 characters and the description within 200 characters when target platforms impose those limits. Use clear Markdown headings and short paragraphs. Add language identifiers to fenced code blocks. Keep prose concise and opinionated, but do not sacrifice necessary reasoning, conditions, or examples. ### Make input an invitation, not a gate The Input section should explain in plain language what the user may provide and include an example invocation. Treat information supplied in the request as answers already given. Allow partial or zero initial input. Explain how the guided flow will collect missing information instead of blocking the user. Avoid runtime-specific placeholders or template syntax that will appear literally in unsupported environments. ### Design interactive flows deliberately For an interactive skill: - Ask one question at a time or use small, coherent batches. - Let each answer shape the next question. - Offer numbered, context-aware next-step recommendations. - Allow selection by number as well as custom input. - Adapt the workflow when the user's choices change the relevant path. Make the skill self-contained and usable by an agent without hidden assumptions. Include at least one explicit anti-pattern and explain why it fails. ## Check skills and their links with the library's own tools before sharing ### Use the library's own validation path Prefer the repository's documented discovery, validation, packaging, and full-library test tools over ad hoc checks. Use file discovery and targeted reference searches to verify skill locations and cross-references before submitting changes. Validate that canonical skill paths resolve, metadata is valid, required sections are present, examples and references are accurate, and links remain consistent. When automated tests are unavailable, perform these checks manually rather than claiming unverified success. Run the package builder and catalog generator through their maintained entry points. If a preview application changed, exercise the relevant local preview path and verify its documentation. ### Preserve compatibility and safe automation Honor platform-specific packaging requirements, including exact filename capitalization where required. Keep supporting scripts deterministic, documented, and free of network access unless the workflow explicitly requires and governs it. Review scripts and packaged content for safety before sharing or running them. Do not remove managed marketplace, plugin, or compatibility files merely because they appear unrelated. Do not edit generated release artifacts as a substitute for fixing their canonical source. ### Verify the true source of truth Before changing a category, skill type, or package structure, anchor the decision in local criteria and the relevant canonical skill. Prefer evidence from maintained validators and repository tools over personal convention. If the requested work belongs to another repository, stop the write at the current boundary and direct the change to the owning source. Reference material may inform the work without becoming the edit target. ## Keep changes small and run a release checklist before publishing ### Prepare reviewable contributions Keep changes small, maintainable, and scoped to the stated purpose. Use clear imperative commit subjects. A review request should summarize the change, link relevant issues, identify the skill type, and call out meaningful compatibility or behavior changes. When adding or renaming a skill, update catalog entries, counts, tables, paths, and cross-links. Verify that all references resolve before release. ### Apply a complete release checklist - Validate canonical skill folders and metadata. - Rebuild downloadable packages and generated catalogs from source. - Confirm that examples, references, and navigation links remain accurate. - Verify frontmatter syntax and any platform-specific package copies. - Update interface documentation and release notes when a preview application changes. - Check that no generated artifact, unrelated file, or unintended broad replacement entered the change. ### Use educational outcomes as the final gate A release-ready skill is pedagogic, agent-ready, self-contained, and practical. It includes reasoning, at least one worked example, an explicit anti-pattern, defined jargon, and visible trade-offs. A fully developed skill also includes a reusable template and contrasting domain examples. Do not remove explanation, anti-patterns, or examples merely to reduce length. Approve the release only when the skill produces a useful result, strengthens the user's judgment, and remains maintainable across its supported environments.