Organize a Research Skill Library for AI and Publish Only Checked Skills

## Sort Each Skill Into One Stage of the Research Process Define the library's mission before choosing its folders. A research-oriented collection should support the path from question and literature review through ideation, data preparation, experimentation, training, evaluation, deployment, and communication. Use numbered or otherwise stable categories that reflect that lifecycle. Keep one central orchestration skill that routes work to specialized skills without duplicating their detailed guidance. For each proposed skill: - Identify the lifecycle stage and one owning category. - State the user problem it solves and the conditions for using it. - Name adjacent alternatives and explain when they are a better fit. - Avoid overlapping scope that creates two apparent owners for the same task. Treat the taxonomy as a navigation contract. Update the catalog, counts, descriptions, and roadmap whenever ownership or inventory changes. ## Keep All of a Skill's Files Together in One Folder Give each skill its own directory with a required main guide. Add only the supporting folders the skill needs: - `references/` for deep official documentation, API notes, tutorials, issue patterns, and release history. - `scripts/` for repeatable helper operations. - `templates/` for reusable starting points. - `examples/` for complete representative implementations. - `assets/` for non-code material used by the guide. The main guide is the entry point, not an encyclopedia. It should explain the operational path and link directly to detailed references one level below it. Do not create chains where one reference sends the reader to another reference to discover required instructions. Keep all files needed to execute the skill inside the package so validation, archive creation, and registry synchronization operate on one clear boundary. ## Start the Main Guide With Fixed Fields Like Name and Version Every main guide begins with valid YAML frontmatter using a fixed field contract: - `name`: a unique kebab-case identifier, preferably a gerund that describes the activity. - `description`: third-person text that states both what the skill does and when to use it. - `version`: a semantic version updated whenever behavior or guidance changes. - `author`: an ownership value used by registry source classification. - `license`: the distribution license. - `tags`: title-cased terms, while established acronyms remain uppercase. - `dependencies`: optional packages with explicit version constraints. Do not quote scalar values unless YAML syntax requires it. Keep descriptions below the configured character limit and avoid vague identifiers such as helper, tools, or utilities. Validate the descriptor by parsing it, not by visual inspection. Treat missing required fields, invalid versions, duplicate names, and malformed dependencies as blocking errors. ## Keep the Main Guide Short and Move Details to Reference Files Target 200 to 500 lines for the main guide. If essential guidance exceeds 500 lines, move advanced detail into direct reference files instead of compressing away necessary decisions or allowing the entry point to grow without bound. The guide should contain: - A concise purpose and clear trigger conditions. - A comparison with relevant alternatives. - Two or three complete workflows for complex use cases. - Copy-ready checklists where sequence matters. - Concrete input and output examples. - Feedback loops that validate, correct, and repeat quality-critical work. - A common-issues section with specific remedies. Assume a capable reader. Explain domain-specific choices and failure modes, not basic concepts already implied by the task. Give every fenced code example a language identifier. Build substantial references from authoritative sources, with an explicit coverage target such as roughly 300 KB when the domain warrants it. Do not pad documents to hit a size metric; completeness, traceability, and practical usefulness remain the goal. ## Add or Improve a Skill by Following the Same Steps Each Time For a new skill: 1. Select an approved roadmap item and owning category. 2. Create the standard package structure. 3. Write and validate the descriptor before expanding the body. 4. Build the main workflows and decision guidance. 5. Add direct references, helpers, templates, and examples as needed. 6. Test the skill on representative real tasks. 7. Update the catalog, statistics, and roadmap in the same change. For an existing skill, preserve the descriptor contract, increment the version, keep the main guide within its limit, add missing workflows or troubleshooting, and rerun representative use cases. Use a feature branch and a focused review request. Commit the whole package and its catalog changes together so the repository never advertises an incomplete skill. ## Check Skills With Automatic Checks and Real Tasks Run mechanical checks before review: - Confirm the main file exists and its frontmatter parses. - Count main-guide lines against the 200-to-500 target. - Verify every code fence declares a language. - Measure reference coverage against the chosen target. - Check that referenced files exist exactly one level below the main guide. - Confirm names, tags, versions, and dependencies follow their schemas. Then perform behavioral validation: - Run each primary workflow with realistic inputs. - Verify the stated outputs and recovery steps. - Exercise at least one common failure. - Confirm an alternative is recommended when the skill is not the right tool. - Repeat after any material edit. A large reference folder does not compensate for a vague workflow, and a polished overview does not compensate for unusable examples. ## Upload Changed Skills to the Skill Catalog Automatically After Approval On an approved change to the default branch, detect which top-level skill packages changed. For each changed package: 1. Require the main guide and parse its descriptor. 2. Classify the source according to the declared ownership policy. 3. Archive the complete package, excluding hidden operating-system and version-control files. 4. Upload the archive to the matching registry namespace. 5. Create or update the registry record. 6. Report skipped or failed packages without silently treating them as synchronized. Store endpoint and authentication values only in the automation platform's secret store. Support a manual trigger for recovery and testing, but ensure the same validation and packaging logic runs in both automatic and manual modes. Verify the workflow with a harmless versioned change, inspect the automation run, confirm the registry record and archive, and avoid using unreviewed edits merely to trigger the pipeline. ## Publish a New Package Only When Its Version Number Changes Drive package publication from a version change in the package descriptor on the default branch. A lockfile-only change must not publish a new release. Use the package manager's version command so the descriptor and lockfile advance together. Select patch, minor, or major according to compatibility, and suppress automatic version-control tags only when the repository's release process requires a separate commit. Authenticate through a configured trusted publisher rather than a long-lived registry token. Attach build provenance or an equivalent supply-chain attestation to every published artifact. Before publication, verify: - The trusted-publisher identity matches repository and workflow names exactly. - Environment variables do not override trusted authentication with a stale token. - Clean installation succeeds from the committed lockfile. - The new version differs from the previous revision. - The package contents match the reviewed source. If publication is skipped or authentication fails, fix the version gate or trusted identity; do not bypass provenance. ## Improve Existing Skills Instead of Piling Up New Ones Judge the library by executable expertise, not the number of directories. A useful skill distills reliable practice into a form an agent can follow, verify, and recover. Before merging, confirm: - Scope fits one category and does not duplicate an existing owner. - Descriptor, naming, and version rules pass. - The main guide stays focused and all required detail remains reachable. - Workflows, checklists, examples, alternatives, and troubleshooting are present where needed. - Real tasks validate the guidance. - Catalog, roadmap, archive automation, and package release data remain consistent. Prefer improving an existing skill over adding a near-duplicate. Prefer one complete workflow with a working feedback loop over many shallow examples. When a metric conflicts with clarity or correctness, preserve the useful decision guidance and document why the metric was not the right proxy.