instar-concepts
The Skill primitive is the first formally-specified Layer-3 required functional primitive from the framework-functional-parity foundational work. This spec defines what a Skill is in Instar terms — in
SKILL.mdspecs/instar-concepts/skill.md
GitHubSkill — Instar concept spec
What this is
The Skill primitive is the first formally-specified Layer-3 required functional primitive from the framework-functional-parity foundational work. This spec defines what a Skill is in Instar terms — independent of any framework's specific file layout, frontmatter convention, or discovery mechanism — so that the per-framework specs (specs/frameworks/<framework>/skills.md) and the eventual parity rule (src/providers/parity/rules/skillParityRule.ts) have a single source of truth to render from and verify against.
This is the prototype shape every subsequent primitive concept spec (Hook, Agent, Tool, Memory) will follow.
Primitive identity
| Field | Value |
|---|---|
| Layer | 3 (functional) |
| Classification | Required |
| Foundational-spec reference | specs/instar-foundations/required-primitives-inventory.md → entry #1 |
| Substrate dependencies | agenticSession, toolAccess, toolAllowlist |
Definition
A Skill is a reusable behavioral capability — a markdown instruction file plus optional bundled scripts, references, and assets — that the agent can invoke explicitly via a slash-command surface AND that is automatically considered by the model based on a natural-language description.
Three things make something a Skill (versus a plain prompt template or a tool):
- Discoverable identity. It has a stable
namethat maps to a/<name>slash command AND adescriptionshort enough to fit in the model's metadata-loading budget. - Lazy body. The body of the skill (instructions, references, scripts) is loaded into context ONLY when the skill triggers — either via explicit slash invocation or via the model recognizing the description matches the user's intent.
- Bundled resources. The skill can carry scripts, references, and asset files in sibling subdirectories that the skill body refers to.
A Skill is NOT:
- A single-prompt template (no lazy loading, no bundled resources).
- A tool (a tool is invoked mid-turn by the model; a skill orients the agent toward a workflow).
- A persona (a persona has its own session — an Agent primitive, spec TBD).
Canonical source-of-truth
Per the foundational spec's gap-fill principle, Instar defines the canonical master format. Each enabled framework's per-framework spec describes how Instar renders that master into the framework's native discovery shape.
Canonical path (on a deployed agent): .instar/skills/<name>/
Slug grammar (load-bearing). Skill <name> must match ^[a-z0-9][a-z0-9-]{0,63}$ (lowercase alphanumeric + hyphens, starts with alnum, max 64 chars). The grammar is enforced at every entry point — directory listing, frontmatter parsing, every renderer's path construction. Path traversal (../etc, /abs/path, names with spaces or capitals) is rejected at the canonical-read layer, before any write ever runs. This makes the mirror-trust auto-remediate path safe under attacker-controlled canonical content.
Directory-name authority. The on-disk directory name IS the slug. Frontmatter name: MUST match the directory name; mismatch is a canonical-read error. This resolves the "which wins?" ambiguity authoritatively.
Canonical contents:
.instar/skills/<name>/
├── SKILL.md (required — frontmatter + body)
├── scripts/ (optional — executable resources)
├── references/ (optional — context-load-on-demand docs)
└── assets/ (optional — output resources)
Canonical frontmatter (v0.1 — minimum viable):
---
name: string # required, slug grammar enforced — maps to /<name>
description: string # required — natural-language intent matcher
# sanitized at parse time: control chars stripped, whitespace collapsed,
# capped at 256 chars. Bounds prompt-injection surface.
metadata:
short-description: string # optional — UI-display short form
---
YAML parsing uses js-yaml with FAILSAFE schema (no JS-type coercion). Parse errors fail loud at the canonical-read layer, surfaced as canonical-read-error. Git-merge-conflict markers in the file are detected and rejected before parsing.
Deferred to v0.2 (tracked, NOT in current rendering contract):
allowed-tools: string[]— will land with the Tool primitive, where the Claudeallowed-toolsfrontmatter + Codexdependencies.toolsmapping is the load-bearing concern. Removing the field from v0.1 closes a spec-vs-code drift gap rather than promising tool-restriction the renderer doesn't enforce.user-invocable: bool— Claude's framework-native field; v0.1 leaves Claude's default (true) in place.icon-small,icon-large,brand-color— Codex-bonus rendering surface; will land in a follow-up when canonical icon-bundling is designed.
Every per-framework rendering MUST honor name + description faithfully (these are the primitive contract). Optional fields are honored when the framework supports them and silently dropped when it doesn't.
User-edit detection via stamp. Every rendered SKILL.md and openai.yaml carries an x-instar-stamp: <sha256-of-canonical-body> field. On verify, if the rendered body differs from canonical AND the stamp matches the current canonical body hash → the user edited the rendering directly (surfaced as user-edit-conflict, NOT auto-overwritten). If the stamp is stale or missing → canonical changed since last render (legitimate body-content-mismatch, eligible for auto-remediate). This makes the "rather than silently overwriting" promise in the source-vs-rendering authority section structurally enforced, not aspirational.
Per-framework rendering targets (current set)
Each framework's spec at specs/frameworks/<framework>/skills.md is the authoritative renderer description. Summary:
| Framework | Renders canonical → | Sibling artifact | Discovery scope |
|---|---|---|---|
| Claude Code | .claude/skills/<name>/SKILL.md |
none required (frontmatter top-level only) | project-local |
| Codex CLI 0.130 | .agents/skills/<name>/SKILL.md |
.agents/skills/<name>/agents/openai.yaml (interface metadata) |
project-local |
Future frameworks add a row + their own specs/frameworks/<framework>/skills.md describing the rendering contract.
Parity contract
Invariant: for every (skill × enabled-framework) pair, the rendered output must:
- Exist at the framework-native path.
- Match the canonical SKILL.md body byte-for-byte (after frontmatter transformation).
- Carry name + description faithfully in the framework's expected location.
- Carry the
x-instar-stamphash so user-edits can be distinguished from canonical drift. - Co-locate all required sibling artifacts (e.g., Codex's
agents/openai.yaml). - Mirror bundled subdirectory contents (
scripts/,references/,assets/) byte-for-byte (symlinks skipped to prevent tree-escape).
Symmetric verify (orphan detection). The parity rule walks BOTH directions:
- For every canonical skill → verify all enabled frameworks have a correct rendering.
- For every rendered skill dir → verify a canonical counterpart exists. Rendered dirs without a canonical → surfaced as
orphan-rendering-found, eligible for removal.
Drift in any of the six triggers the parity sentinel's re-render action (per the trust-level-mirrored auto-fix policy locked in specs/provider-portability/13-framework-parity-sentinel.md). Orphans are remediated by removal, not re-render.
Refusal conditions. Auto-remediate refuses to proceed when:
- Canonical violates slug grammar or fails to parse (surfaced as
canonical-read-error). - Rendered file is a
user-edit-conflict(user-edits via direct file edit are not auto-overwritten; operator must resolve). - Rendered dir name violates slug grammar (orphan-removal is refused for safety, even though detected).
What is NOT part of the Skill primitive
Per the foundational spec's "What is NOT a functional primitive" framing, these adjacent things are out of scope:
- The slash-command parser — that's the Slash-command primitive (#8), which wraps Skill but is its own contract.
- The intent-classification model — that's the agent's substrate-level use of
oneShotCompletion, not a Skill concern. A Skill'sdescriptionis content the classifier reads, not classifier logic. - Script execution sandboxing — that's the substrate's
bashExecution+toolAllowlistcapabilities; a Skill just declares which tools it needs. - MCP server registration — separate Layer-3 primitive (#11, bonus).
- The conversational discovery surface ("can we install a skill that does X?") — that's the Conversational-action primitive (#10), which uses Skill as one of its action targets.
Source-vs-rendering authority
- Canonical source is authoritative. When the parity sentinel detects drift, the canonical source wins and the rendering is re-derived.
- Manual rendering edits are conflicts. If a user edits
.claude/skills/<name>/SKILL.mddirectly, the sentinel surfaces the divergence (per the Q3-resolved policy: sibling-files for framework-specific extras, conflict-to-user for body edits) rather than silently overwriting. - Framework-specific extras live in sibling files. If Codex grows a feature that needs additional per-skill state, it goes in
.agents/skills/<name>/<framework-specific>.yaml, NOT in the canonical SKILL.md.
Open questions tracked here
Bundled-asset rendering for icons — Codex's
openai.yamlcan reference icon paths (./assets/icon.png). If the canonical doesn't declare icons, we don't render the icon fields. If it does, paths must remain relative-to-skill-dir after rendering. Trivial; no spec change needed.User-added skills via conversation — when a user says "create a skill that does X", the conversational-action primitive (#10) calls the canonical Skill writer, not the per-framework renderers. Per-framework rendering is the parity sentinel's job downstream.
Migration of existing
.claude/skills/content — agents that already have skills under.claude/skills/but no canonical.instar/skills/need a one-time backfill. Out of scope for this spec; the parity sentinel design (specs/provider-portability/13-framework-parity-sentinel.md) handles backfill via its initial-scan path.
Alignment with foundational specs
framework-functional-parity.md: Required primitive, three-layer model honored (Skill consumesagenticSession+toolAccesssubstrate primitives), gap-fill principle followed (Instar defines canonical, frameworks render).required-primitives-inventory.md: Entry #1 "Skill". Per-framework status updates on rendering completion (Codex moved frompartial ⚠️tonative ✓after PR #249).- What-is-NOT bound respected: classifier logic, command parser, sandboxing all kept out.
- Substrate-dependency declaration matches inventory.
Implementation slice for the first prototype PR
This concept spec ships alongside:
specs/frameworks/claude-code/skills.md— Claude rendering contract (path, frontmatter shape, what's loaded when, known quirks).specs/frameworks/codex-cli/skills.md— Codex rendering contract (path, siblingopenai.yamlshape, trust-level prerequisite, known quirks).src/providers/parity/rules/skillParityRule.ts— The first concrete parity rule:- Strict slug grammar at every entry point (path-traversal safe).
- YAML parsing via
js-yamlFAILSAFE schema; fail-loud on parse error. - Symmetric verify (canonical → frameworks AND frameworks → canonical for orphans).
x-instar-stampfield tracking on rendered files; user-edit-conflict distinguished from canonical drift.verify(projectRoot, name)returns mismatches withreasonCodeenum.remediate(projectRoot, name, framework)re-renders from canonical; refuses on user-edit-conflict.listOrphans()+removeOrphans(framework)for the orphan-cleanup leg.
src/providers/parity/registry.ts— Minimal registry that the futureFrameworkParitySentinelwill consume.- Unit tests covering: slug-grammar enforcement (path traversal rejected, capitals rejected, spaces rejected), canonical-read errors tagged with
framework: 'canonical', YAML parse fail-loud, git-merge-conflict marker detection, orphan detection + removal (refused for non-slug names), user-edit-conflict via stamp, description sanitization + truncation, symlink-skip in mirror, render correctness for both frameworks, idempotent re-render.
v0.1 deferred items (tracked as follow-ups, NOT in this PR)
migrateSkillsCanonicalBackfill()— PostUpdateMigrator entry that scans existing.claude/skills/and.agents/skills/, backfills any unknown skill into canonical at.instar/skills/. Without this, the parity rule is a structural no-op on existing agents (their canonical dir is empty). MUST ship before the sentinel auto-runs on real agents.installBuiltinSkills()rewrite — currently writes to.claude/skills/directly; should write to canonical + trigger remediation.BackupManager.DEFAULT_CONFIG.includeFiles— add.instar/skills/; explicitly exclude.claude/skills/and.agents/skills/(derived).templates.ts → generateClaudeMd()— update Agent Awareness section to reference canonical path + slash-command surface.allowed-toolsrendering — lands with the Tool primitive (separate PR in the roadmap).- Atomic write (tempfile + rename) — single-machine + single-sentinel-pass narrows the v0.1 race window; will add when the sentinel ships.
- Sentinel per-rule disable knob — config-side surface for the sentinel, not the rule.
E2E tests against real Claude + Codex sessions are queued as a follow-up that needs healthy sessions on both frameworks; the unit tests against tmp filesystem fixtures provide structural correctness pending live verification.
Convergence-round-1 record
Round 1 (2026-05-18) ran with 6 reviewers in parallel (4 internal: security, scalability, adversarial, integration; 2 external: GPT 5.4, Gemini 3.1 Pro). Grok was not available this session (no XAI_API_KEY configured); deviation from the canonical 7-reviewer set is documented in the convergence report.
Material findings addressed in this iteration:
- C1 (path traversal via name) — strict slug grammar at every entry point.
- C2 (hand-rolled YAML parser) — replaced with
js-yamlFAILSAFE schema. - C5 (orphan detection / asymmetric verify) —
listOrphans()+removeOrphans()added; verify walks both directions. - C7 (user-edit destruction) —
x-instar-stampdistinguishes user-edit-conflict from canonical drift; remediate refuses to overwrite conflicts. - C8 (description prompt-injection surface) — control-char strip + length cap at parse time.
- H1 (directory-name vs frontmatter-name authority) — directory name is authoritative; mismatch is
canonical-read-error. - H5 (canonical-read errors mis-tagged) —
framework: 'canonical'slot added to the type union.
Material findings deferred to follow-ups (tracked above): C3 (allowed-tools rendering), C4 (backfill migration), C6 (atomic writes), H2/H3 (backup + template updates), H4 (git-sync conflict surfacing — partial; parser fails loud on conflict markers).