Write and Release Agent Skills That Trigger Correctly and Pass Validation

## Keep Skill Descriptions to What It Does and When to Use It Treat the description as routing metadata, not a compressed procedure. Agents may choose a skill from its description before reading the full body, so embedded process steps can override or bypass the detailed workflow. Write descriptions as a brief capability statement followed by triggering conditions: what the skill does and when to use it. Keep the description within the active schema limit, including a 1,024-character maximum when that limit applies. Never place ordered steps, implementation sequences, or troubleshooting procedures in the description; put all how-to guidance in the skill body. Test descriptions with realistic prompts to confirm that they trigger for intended requests, remain inactive for unrelated work, and lead the agent to the full instructions. ## Use Only Spec-Defined Frontmatter Fields and Valid Skill References Follow the active skill specification rather than copying fields from a neighboring repository. Keep only specification-defined fields at the top level, including `name` and `description`; use `license` and `allowed-tools` only according to the repository contract. When present, `allowed-tools` must be a space-delimited list. Place repository-specific fields under `metadata`. Restrict names to letters, numbers, and hyphens. Validate descriptions for length and trigger wording. Keep structured metadata such as author, semantic version, domain, triggers, role, scope, output format, and related skills within repository-defined enums and formats. Every related-skill entry must resolve to an existing skill directory. Use the repository-approved license value consistently; when the repository fixes the license to MIT, write `license: MIT` exactly. Do not accept unknown enum values, broken references, or custom top-level fields merely because the YAML parser accepts them. ## Keep the Main Skill File Short and Move Details to Reference Files Keep the main skill file compact enough to load as routing and operating context. A practical first tier is roughly 80 to 100 lines containing the role, triggering guidance, a five-step core workflow, mandatory and prohibited behavior, and a routing table to deeper references. Place detailed technical material in focused second-tier reference files, typically 100 to 600 lines each. Each reference should cover one topic, include complete working examples with relevant types, explain edge cases and anti-patterns, and state when the guidance should and should not be used. Load only the references required by the current task. Cross-link related skills where useful, but do not duplicate their full content. Treat reduced context use as a design outcome; a well-routed two-tier structure can target about a 50% reduction without removing necessary instructions. ## Use Each Framework's Built-In Mechanisms in Examples Framework-specific guidance must use the framework's established mechanisms. If the framework provides global error handling, middleware, dependency injection, lifecycle hooks, or another built-in abstraction, examples should use that mechanism instead of recreating it manually. Do not force one generic architecture across unrelated frameworks for the sake of repository-wide visual consistency. The framework's conventions for error handling, organization, testing, and integration take precedence. Keep reference examples complete and executable, with types when the language supports them. Review examples against the framework version in scope and reject patterns that duplicate built-in behavior or conceal framework-specific constraints. ## End Every Skill File With One Documentation Link Every skill file must end with exactly one canonical documentation backlink as its final line. Use Markdown link syntax with the label `Documentation` and the canonical URL, not a bare URL, so strict renderers produce a real hyperlink. Derive the canonical path from stable metadata, such as `metadata.domain`, and the skill directory name. Apply the documented fallback domain when metadata is absent. When adding or renaming a skill, update the directory, domain, and backlink together; otherwise the published link can return a missing page. Account for multiple publication surfaces explicitly. Raw-file aggregators may need the backlink for discovery, while the documentation build may strip the same self-link from generated pages, mirrors, and language-model indexes. Preserve both behaviors in the synchronization step and test the rendered destination. ## Check for Overlap and Update References When Creating or Changing a Skill For a new skill: 1. Check existing skills for overlapping responsibilities. 2. Write the main skill with capability and trigger metadata, leaving process steps in the body. 3. Add focused references for deep content. 4. Add a routing table from topics to references. 5. Append the single canonical documentation backlink as the final line. 6. Test triggering and non-triggering prompts. 7. Update the skill guide and domain indexes when the taxonomy changes. Before modifying a skill, read its full current body and the references affected by the change. Preserve the capability-and-trigger description shape and the progressive-disclosure architecture. Update routing tables, related-skill references, documentation indexes, and trigger tests whenever names, scope, triggers, or dependencies change. ## Keep Counts and the Changelog in Sync With One Version File Use one version manifest as the source of truth for the release version and computed counts such as skills, workflows, and reference files. Run the repository update tool to recompute counts from the filesystem and synchronize generated documentation. Support check and dry-run modes so CI and reviewers can detect drift without writing. Add the new release at the top of the changelog using a stable Added, Changed, and Fixed structure, and maintain the version-comparison link. Update guides, decision trees, command tables, and cross-references for new or modified content before regenerating aggregate documentation. Regenerate count-bearing social assets only when the embedded counts change; a version-only patch does not require a new asset. Review the generated diff so automation does not conceal unrelated changes. ## Run the Skill and Markdown Validators Before Release Run the skill-integrity validator before release. It must check YAML parsing, required fields, name format, description length and the required `Use when` trigger clause, reference-directory existence, reference structure, and count consistency. Provide scoped checks for one skill or one validation family, plus machine-readable output for CI. Run a Markdown validator separately. Check for HTML comments that break tables, unclosed code fences, missing table-separator rows, and inconsistent column counts. Validate the full repository after targeted investigation. Treat exit code 0 as success and exit code 1 as validation failure, while reviewing warnings explicitly. Never publish a release with unresolved validation errors merely because a narrower check passed. ## Record Commands and Results Before Saying a Release Is Ready After synchronization and validation, search for stale version references while excluding intentional changelog history. Manually confirm that descriptions, trigger tests, routing tables, related-skill references, canonical backlinks, generated counts, and conditional assets match the release. Preserve third-party attribution, license notices, and research references when behavioral patterns or process discipline were adapted from other work. Do not remove provenance during cleanup. Record the exact update and validation commands, their results, reviewed warnings, and any intentionally skipped conditional step. Report release readiness only after the full required validators pass and the final diff contains no unexplained changes.