skill-scaffold
Skill Scaffold
Coverage
- Authoring flow: copy → rename → adapt → strip teaching annotations → verify → commit
- Frontmatter identity:
schema_version,name,description,version,type,category,scope,owner, plus the eval-health triple anddrift_checkrequired by every Skill Metadata Protocol v6 skill - Archetype selection: how to pick between
capability,workflow,router, andoverlayand which## H2body sections each archetype requires - v6 understanding fields: when to add
comprehension_state,mental_model,purpose,boundary,analogy,misconception, and when the legacyconceptback-compat block is still useful - Semantic-layer discipline: how
description:(≤ 3 sentences, pushy, boundary-aware routing contract) differs from## Coverage(bulleted scope map of distinct topics) and why each must stay in its own layer - Teaching-layer mechanics: how to use
> **TEMPLATE NOTE:**blockquotes and# TEMPLATE NOTE:YAML comments to teach without cargo-culting meta sections into derived skills - Lint-first authoring gate: passing focused skill lint against your new skill before commit, every time, no exceptions
- Routing-eval honesty: defaulting to
routing_eval: absentand only flipping topresentafternode scripts/skill-graph-routing-eval.js --skill <name>exits 0 - Grounding declarations: when to populate
grounding.truth_sources, when URL truth sources are acceptable, and how local truth-source hashes differ from external references
Philosophy
A scaffold teaches by example, not by placeholder. A concrete, internally consistent specimen of a finished skill is a more reliable authoring reference than any amount of abstract instruction. The teaching layer — meta-commentary about how to read and adapt the scaffold — must live in structurally distinct slots that disappear when the author tightens a new skill, never in the ## H2 section slots that AI agents copy verbatim. Authoring is also a lint-first discipline: the lint output is the primary debugging surface for new skills, deliberately verbose, and the canonical answer to "did I do this right?" — not a senior reviewer's pattern-match.
Authoring Flow
More from jacob-balslev/skills
layout-composition
Use when deciding responsive page or screen structure: section order, scan pattern, grid/flex composition, breakpoints, viewport hierarchy, responsive media, and density. Do NOT use for user-goal decomposition (use `task-analysis`), navigation taxonomy (use `information-architecture`), visual polish (use `visual-design-foundations`), or component/token contracts (use `design-system-architecture`).
8context-graph
Use when designing or auditing the multi-graph context architecture of an AI-coding workspace: skill graph, document routing graph, memory index, script registry, and the cross-graph edges between them. Covers edge typing, orphan detection, connectivity health, deterministic graph synthesis signals, change-propagation checks, and drift or hub-and-spoke anti-patterns. Do NOT use for authoring one SKILL.md (use `skill-scaffold`), validating one skill (use `graph-audit`), live routing decisions (use `skill-router`), context-window budgeting (use `context-window`), or session load/drop choices (use `context-management`).
8visual-design-foundations
Use when designing or auditing visual craft: color palette, typography, spacing, elevation, rhythm, density, visual hierarchy, brand fit, contrast intent, and motion feel. Do NOT use for sign-system meaning (use `semiotics`), token/component architecture (use `design-system-architecture`), responsive structure (use `layout-composition`), or accessibility compliance (use `a11y`).
7project-knowledge-extraction
Use when extracting durable project knowledge from code, docs, issues, incidents, reports, screenshots, or conversations into reusable context such as skills, ADRs, glossaries, context docs, or memory. Do NOT use for writing a new skill contract (use `skill-scaffold`), maintaining library tooling (use `skill-infrastructure`), or generic documentation polish (use `documentation`).
6problem-framing
Use when a team is converging on solutions before agreeing on the problem, when a brief reads as a feature request, when symptoms and root needs are tangled, or when assumptions need surfacing before design work proceeds. Do NOT use for code-level bug triage, runtime failure diagnosis, or root-cause analysis of system errors — those are engineering investigation tasks, not design problem framing.
6ai-native-development
Use when reasoning about agent autonomy levels, designing auto-improve loops, evaluating AI-generated code quality, or measuring agent productivity in an LLM-assisted codebase. Covers Karpathy's three eras of software (1.0 explicit / 2.0 learned / 3.0 natural-language), the vibe-coding-vs-agentic-engineering distinction, the 0–5 autonomy slider with task-type recommendations, the one-asset / one-metric / one-time-box AutoResearch loop, Software 3.0 productivity metrics, and the documented quality regressions of ungated AI-generated code (the 'vibe hangover'). Do NOT use for choosing a specific autonomy-loop topology (use `agent-engineering`), for the per-prompt authoring discipline (use `prompt-craft`), or for reviewing the AI-generated code that comes out of a Software 3.0 workflow (use `code-review`).
6