SkillSeam: Six Principles for Auditing Agent Skill Collections

RESUMO

A folder of competent skills is not yet a reliable system. Skills rarely fail alone; they fail at the seams of a collection. As an agent's skill library grows, procedures compete for attention, aliases double-load, boundaries blur, and poorly sized skills turn routing errors into task failures. We introduce SkillSeam, a method that audits the relationships through which individual skill files become a system. It maps each collection-level principle to a failure mechanism, its strongest observable, and a controlled perturbation test. From one sealed skill system, SkillSeam perturbs six design principles: persistence gradient, system coherence, regime gating, orthogonal coverage, flow, and granularity discipline. Crucially, each principle is evaluated through the channel its failure mechanism predicts rather than through accuracy alone. Flattening the persistence hierarchy increases loaded-skill tokens by 60%; a dangling anchor raises total tokens by 64% and shifts accuracy by -3.1pp; with skill count and context size held fixed, replacing an unrelated control with a synonymous alias raises noncanonical routes from 0/32 to 15/32 and flips half of matched paraphrase pairs; in a candidate-ownership audit, overlapping lanes raise reported ownership conflicts from 0/16 to 14/16; bland triggers drive routing conflicts from 3/32 to 30/32 and inflate loaded-skill tokens 3.7x; and one granularity mis-mix produces the largest accuracy drop, -12.5pp. These outcomes turn six pieces of authoring advice into testable system properties without treating every probe as confirmation. We release the byte-differenced variants, task slices, rollups, and a one-screen design checklist so that other skill systems can measure the same failure channels.