skill-authoring-workflow — A Workflow for Turning Rough Notes into Compliant Claude Skills

Skill Overview

skill-authoring-workflow is a six-stage structured workflow that helps turn rough notes, workshop content, or unfinished prompts into validated SKILL.md skill assets that comply with repository standards. It does not rely on luck or on something “looking fine”; instead, it delivers according to clearly defined completion criteria.

Applicable Scenarios

1. Creating a new skill from source materials: You have meeting notes, research documents, or a framework draft and want to turn them into a reusable PM skill in the repository, but are unsure where to start.
2. Updating an existing skill without breaking standards: You need to modify a published skill while ensuring that its frontmatter, section order, and metadata constraints remain compliant.
3. Running the complete authoring and validation process before submission: Your skill draft is already written, and you want to complete structural checks, metadata validation, and README directory updates in one pass before taking any submission action.

Core Features

1. Six-stage structured workflow: Duplicate-check preflight → draft generation → content refinement → strict validation → repository documentation integration → optional packaging. Each step has clearly defined actions, so the process does not end abruptly after the writing is complete.
2. Reuse of the repository’s native toolchain: Preferentially invokes built-in scripts and metadata checkers such as find-a-skill, add-a-skill, build-a-skill, and test-a-skill, using established workflows instead of reinventing them.
3. Clearly defined Definition of Done: Eight mandatory checks—including valid frontmatter, compliant section order, name and description length requirements, clear triggering conditions, resolvable cross-references, and synchronized README counts—must all pass before the work is considered complete.

Frequently Asked Questions

I only have a pile of rough meeting notes. Can I use it?

Yes. “Rough” is exactly the standard input for this workflow. Its purpose is to move unfinished materials toward a compliant, publishable state—you only need to provide the materials and intent (for example, “Turn these pricing workshop notes into an interactive consulting skill”), and it will begin from the preflight stage without repeatedly asking for information you have already provided. If no materials are available, it will first clarify what you want to convert before starting.

How is this different from simply running the build-a-skill script once?

The script covers only a single stage: the wizard script is suitable when you have an idea but no body text yet, while the content-first script is suitable when you already have source materials. This workflow connects material transformation, type determination, content refinement, validation script execution, README directory updates, and packaging into a complete pipeline. It then reviews each item against the Definition of Done—the standalone scripts do not perform duplicate-check preflight or synchronize directory counts for you.

Once the skill passes validation, can I package and upload it directly to Claude?

Yes. The final stage of the workflow is optional packaging. It supports outputting zip archives by individual skill, category, or preset bundle (such as a core PM skill package), which can be directly uploaded as custom skills to Claude. Note that manual review of the generated content is still recommended before uploading. This workflow explicitly identifies “publishing the generated result directly as the final draft” as an anti-pattern.