AI coding agents are in widespread professional use, yet developer productivity gains remain inconsistent. Controlled studies report speedups of 21–56% in some settings and slowdowns of up to 19% in others. We argue that this variance is not attributable to model capability but to the absence of structured, project-specific knowledge made available to the agent. This paper addresses that gap by introducing SKILL.md files as a first-class design artifact for AI-augmented coding workflows and proposing a two-layer framework for their design. The Foundation Layer consists of a persistent Project Orientation Skill, co-authored by developer and agent, that eliminates per-session context overhead by encoding non-inferable project knowledge— architecture, conventions, domain terminology, and anti-patterns. The Task-Level Loop consists of three sequential skills—Task Decomposition, Code Conformance, and Autonomous Test-Fix— that govern planning, implementation, and validation respectively, with planning acceptance criteria closing the loop at validation. Grounded in six months of daily professional practice and corroborated by practitioner observations from a cohort of 10–15 developers spanning 1–8 years of experience on enterprise .NET, Java, and React projects, and supported by converging evidence from over forty peer-reviewed studies, we derive seven design principles for effective skill authoring. Practitioner estimates suggest net feature completion at approximately 1.5–2× faster than unaugmented workflows (self-reported, directional). We document boundary conditions including an experience-level variation in planning gate engagement and a complex task scope limitation. This work provides practitioners with an actionable framework and researchers with a foundation for controlled empirical followup.
Ayush Basnet (Tue,) studied this question.