Skill Model
How skills encode reusable workflow and implementation contracts
The skill model has two jobs.
Some skills improve the quality of work inside a domain. Other skills shape the run itself. A React skill changes how the agent writes React. A delivery phase changes how the agent moves from intent to implementation, review, validation, and docs closeout.
Specificity
Implementation skills sit on a specificity ladder.
Framework skills are closest to a single domain: React, Next.js, Effect, Better Auth, Drizzle, TanStack, and similar surfaces. Language skills sit above those framework rules. Agnostic skills apply across stacks.
The more specific the skill, the closer it should stay to the code path that makes it true. A Next.js skill belongs near a Next.js surface. An agnostic planning skill can apply across the repository.
Workflow Skills
Workflow skills define a procedure across work, not a domain style. They include skills such as create-plan, create-spec, implement-spec, requirements-grill, and write-backlog.
write-backlog owns the product-facing EPIC plus child stories or sub-issues hierarchy. create-spec targets one EPIC and must harvest every child story or sub-issue under it. create-plan converts that spec into dependency-aware implementation tasks while preserving the EPIC/story links. implement-spec executes the approved plan without dropping story requirements.
Phase skills are mostly agnostic workflow wrappers. They call workflow skills, carry validation gates, and generate explicit leaf-skill guidance for the work at hand.
The phase skill shapes the run. The leaf skill improves the local work.
Atomic Skills
Atomic skills are individual bounded moves. They can run inside a phase wrapper, beside a plan, or as a direct user request.
Examples:
parallel-researchcoordinates split-friendly readonly analysis and then requires synthesis before action.handoffcreates a clean continuation artifact before a fresh, long phase.writing-fragments,writing-beats, andwriting-shapepreserve the writer flow for substantial public docs.
Use Atomic Skills for the operator-level judgment behind these individual skills.
How Skills Enter A Run
A skill enters a run through an explicit trigger: the user names it, scoped guidance requires it, a plan or handoff names it, or a phase wrapper delegates to it.
A loaded skill contributes the local contract for that work: what to read first, which artifacts matter, which outputs are expected, which surfaces can change, and which checks prove completion.
Activation should be explicit enough for the final artifact trail. A completed run should make it clear which workflow contracts shaped the work.
Skills should not become encyclopedias. If the body grows too large, move stable reference material into routed docs, runbooks, or source references and keep the skill focused on execution.
Source Of Truth
Reusable skill changes start in the shared skills repository, not in generated mirrors. In this environment, edit /Users/stefan/Desktop/repos/wearedevpunks-skills first, push that change to wearedevpunks/skills, then run bun run sync:skills in Harness so apps/cli/skills/* and scaffolded .agents/skills/* copies are regenerated from source.
Generated skill mirrors are distribution artifacts. Treating them as the authoring surface creates drift because later syncs overwrite them.
Validation Role
Skills carry proof standards. A skill should tell the agent what counts as done for that slice of work: tests, review evidence, runtime evidence, docs ingest, or a valid no-op reason.
Model Before Reference
The Skills and Packs wiki should explain the model, not list every skill the harness can install.
Use Skill Reference when you need the practical lookup: skill name, when to use it, pack/category, and source SKILL.md. Individual concept pages only make sense when a skill has enough durable theory to justify its own article. Otherwise the executable skill file remains the contract.