Build and Maintain a Skill Library That Works With Any AI Agent

## Organize Folders So Skill Details Load Only When Needed Give every skill its own directory with a primary instruction file, required metadata, and optional reference and script directories. Keep complete examples, research material, canonical templates, and collection-level documentation in clearly separated locations. Maintain a root skill map so a user or agent can discover the collection without loading every skill body. Treat names and descriptions as the startup index. Load detailed instructions, references, and scripts only when a skill activates. This structure preserves attention for the current task while leaving deeper material available on demand. ## Keep Each Skill's Main File Short and Usable With Any Tool Keep a skill's primary instruction file below 500 lines and move detailed material into references. Require YAML metadata with a name and third-person description, use lowercase hyphenated directory names, and challenge every paragraph for information value. Assume an advanced audience unless the skill explicitly teaches fundamentals. Write platform-agnostic guidance. Abstract vendor-specific tools unless a platform constraint is essential, and make examples portable rather than presenting conceptual pseudocode as production-ready code. ## Write When Each Skill Should and Should Not Be Used Include sections for activation conditions, core concepts, practical guidance, examples, guidelines, gotchas, integration, and references. Every activation section must state positive triggers and a do-not-activate boundary that routes adjacent work to the correct skill. Give special weight to experience-derived gotchas because they capture failure modes that generic guidance often misses. In integration guidance, refer to other skills by stable plain-text names when links would break across installation layouts. ## When a Skill Changes, Update the Lists and Where Its Numbers Come From When adding or changing a skill, update the collection overview, distribution manifests, and corpus index together. Map the skill to its activation scenarios, reusable behavior mechanisms, and supporting claims so discovery, packaging, and evaluation describe the same artifact. Record provenance for numeric, benchmark, volatile, or vendor-performance claims. Update mechanism and claim registries whenever a skill introduces a reusable behavior change or evidence-sensitive assertion; do not leave those relationships implicit in prose. ## Run Automatic Checks Before Asking an AI to Judge Before accepting a change, run the repository's declared checks for metadata parsing, strict schema and corpus structure, platform-compatible installation layouts, skill-body health, activation boundaries, and adversarial benchmarks. Treat these as review gates rather than optional diagnostics. Validate structure, manifest synchronization, rubric arithmetic, retrieval state, and registry shape deterministically first. Use model-based judgment only after those checks pass, and do not use a model to excuse a reproducible structural failure. ## Use Each Example Project's Own Setup and Test Commands Do not invent a top-level build system when the repository has none. Identify the runtime and package manager declared by each example or subproject, then use its own setup, build, test, lint, format, and type-check commands. Keep environments and dependencies scoped to that subproject. Run the smallest relevant command while iterating, then complete the subproject's documented gate set before review. Distinguish compilation, unit tests, asynchronous tests, linting, formatting, and static type checks rather than treating one successful command as proof that all gates passed. ## Move Each Research Run Through Set Stages With the Provided Tool Initialize every research run through the provided lifecycle tool so it creates the state file, queue entry, thread log, source-evaluation scaffold, and mechanism proposal template consistently. Advance through retrieval, evaluation, proposal, novelty review, run validation, review readiness, and closure using supported transitions; never edit run state by hand. Validate active runs independently from repository-wide gates. Promote a proposed mechanism only after the run is ready, the required reviewer is recorded, and the readiness check passes. Add claim provenance before a numeric, benchmark, or volatile assertion enters a skill. ## Keep Automatic Research Loops From Calling Paid AI Until a Budget Is Set Expose deterministic commands for discovery, one-step advancement, daily processing, and status reporting, whether the loop is launched manually or by a platform-specific scheduler. Keep retrieval usable without paid model calls, and do not invoke paid models from unattended loops until an explicit budget gate exists. Treat queues, runtime logs, snapshots, status reports, parked reviews, event streams, failures, and ordinary run directories as operational state rather than source. Never commit them except for a deliberately designated seed run. ## Ship Related Skills as One Package Instead of Copies When a host caches every plugin source separately, distribute a related skill collection through one package instead of pointing multiple packages at the same source tree. This prevents redundant caches while preserving one coherent version and manifest boundary. At startup, expose only the metadata needed for discovery. Defer full skill bodies and supporting resources until activation so package breadth does not become permanent context overhead. ## Give the AI Less Material and Get a Person's OK Before Sending Changes (Push) Prefer context quality over context quantity: limited attention and middle-position loss mean that more material can reduce performance. Use sub-agents to isolate attention for bounded work, not merely to imitate organizational roles. Keep conceptual examples portable, such as language-neutral or widely readable pseudocode. Let deterministic evidence precede model judgment, and keep remote publication under human control. Agents may prepare changes and pass every local gate, but they must obtain explicit human approval before pushing or merging them.