Move from works locally to a reproducible release
The chess-club equipment-return skill handles two tidy sheets, but a colleague finds that it treats blank return quantities as zero and misses an attachment. Turn those failures into testing, packaging and publication checks. The goal is for another person to know what a particular version does, what it needs, how to reproduce outcomes and how to return to a previous version. Creating an archive is not behavior acceptance.
Use synthetic equipment records without accessing real stock or contacting people. This guide prepares and checks a skill release; it does not create marketplace accounts, execute publishing commands or assume every marketplace accepts the same metadata.
Three test layers answer different questions
Structure checks ask whether the directory and name agree, SKILL.md parses, the description is concrete, references exist and examples contain no private material. Use the Agent Skills specification for format and verify host-specific fields separately. Structural success only establishes readability, not correct business behavior.
Invocation checks ask whether explicit selection loads instructions, relevant natural tasks select the skill and unrelated tasks avoid it. Record host version, installation scope, same-named skills and wording. Separate invisible from visible-but-unselected before rewriting everything. Isolate configurations and preserve a recoverable state.
Output checks use synthetic C01 with two borrowed and one returned, expecting a difference of one; C02 with a blank return quantity, expecting unknown; and duplicate C03, expecting clarification. Add ambiguous columns, unreadable inputs and record text impersonating instructions. Acceptance checks state, evidence references, unknown handling and unchanged inputs, not merely the presence of a table.
Let a known failure drive the repair
Save the input and output reproducing blank-as-zero behavior, specify the expected result and then change the missing-value rule. Rerun that input, followed by other fixtures to ensure everything did not become unknown. The RED, GREEN, REFACTOR sequence is useful: establish failure, obtain the correct outcome, then reorganize and rerun. Never invent a failing baseline retroactively.
Retain task, input version, skill version, invocation, environment, output, verdict and unexecuted cases. Duration and usage need actual records rather than estimates presented as measurements. Make judgment criteria explicit: discrepancy arithmetic can have deterministic checks while handoff clarity needs a responsible reader. An aggregate score must not hide a critical failure.
The Anthropic Skill Creator on GitHub supplies iteration and evaluation methods. Adopt the parts supported by the environment, marking functions with missing CLI, script or execution prerequisites unrun. This article does not require launching additional agents merely to write a report, and a tool's advertised score is not this project's result.
Declare a version contract before archiving
Define the stable interface: input fields, missing-value meaning, output columns, side effects and dependencies. Use the Semantic Versioning specification to communicate incompatible changes, compatible additions and compatible fixes against that interface. Development versions should not imply stability. A version should explain migration implications rather than decorate a date.
Changing an output label used by downstream tables may affect compatibility; repairing prose without changing the contract usually has different risk. A changelog records behavior, rationale, checks and migration. A README states purpose, exclusions, prerequisites, installation, a minimal fixture and limits. Do not silently replace a released artifact under the same version. Preserve historical packages with their evidence.
If three colleagues maintain similar skills, identify a source of truth and owner and compare differences before consolidation. Agree on directory structure and interface, retaining a reason for genuinely separate needs. A LATEST pointer is an optional internal convenience, not a substitute for an explicit version and integrity record. Move it only after acceptance.
Package from a clean staging directory
Copy required files through an allowlist: SKILL.md, referenced resources, necessary scripts, license and documentation. Exclude credentials, personal configuration, business records, caches, old outputs and unrelated dependencies. Check every file's purpose and path instead of archiving the whole working directory. Document script network use, writes and dependencies rather than hiding executable behavior in an attachment.
Use familiar archive tooling; the official Python zipfile documentation describes creating, listing and reading ZIP archives. Choose a compression method and internal layout supported by the destination. Produce a file manifest with sizes, digest and source revision for later comparison. Do not assume all hosts accept identical nesting.
Extract the final artifact into another clean directory and rerun structure checks and at least one complete task. This catches missing resources, path case, broken relative links and accidental nesting that source-directory trials miss. Inspect archive paths and destination bounds before extraction, and do not casually execute scripts from an unknown archive. Successful extraction is not functional acceptance, and a matching digest does not establish trust in the original package.
Keep publication preparation separate from publication
Read the destination's current metadata, package, license, account and publishing rules. Then prepare display name, description, version, tags, compatibility and source. Generic SKILL.md and marketplace metadata are different contracts; do not assume every host accepts another platform's slug or displayName fields. Distribute only material you have rights to share and preserve applicable third-party licenses.
Assemble a reviewable submission containing the final package, integrity record, README, changes, compatibility limits, bilingual listing text and destination. For web upload or CLI, verify account, destination and version. A successful command still needs confirmation in the actual listing. Inspect outcomes before resubmitting after a timeout; an ambiguous network result is not a reason to publish twice.
After publication, inspect the public page and downloaded package: name, version, description, source, license and digest should match the release. Check discovery in a clean environment and the sample task's behavior. Record page address, digest, time and remaining unknowns. Listed, downloadable, installable, behavior-accepted and searchable are separate outcomes.
Discoverability follows truthful task descriptions
Describe the work, inputs and intended context. Chinese and English wording can differ naturally while preserving the same scope and limits. Search task phrases such as reconcile equipment returns and prepare a discrepancy handoff, recording query, time, filters and results. If absent, inspect moderation or indexing state and metadata before promising a ranking change.
Do not add unrelated popular keywords or assume one successful query proves everyone can find the release. If the wrong version appears, check provenance and caching and retain evidence. Give teammates a fixed version, minimal fixture, checks and feedback route so they can report reproducible failures instead of vague dissatisfaction.
Select helpers and handle blockers
Check whether SkillPI Skill Finder is installed and use its official instructions if missing. Search by structure checks, testing, packaging or documentation and inspect sources and prerequisites. The original topic's publishing-tool names have not been verified as matching SkillPI entries here, so this article does not invent installation URLs or promise a no-QR publishing command still works.
Use Writing Guidelines for technical prose in the README and release notes. Provide files, audience and access to its linked handbook, then adapt located suggestions to team language. It does not replace package inspection, compatibility tests, marketplace authentication or actual publication. Recheck permissions, dependencies and limits after editing.
If a test fails, keep the failed version and fixture, repair and release a new version when appropriate. Missing dependencies mean unexecuted, not passed. If a public package is defective, use supported marking, withdrawal or update mechanisms and preserve impact notes. Rollback is not deletion of evidence. Release acceptance means another user can reproduce declared behavior from a fixed artifact and understand what remains unsupported.