Menu
string # required — natural-language intent matcher
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
Instar-specific development skill used by the instar-developing agent (Echo, or any agent assigned instar-dev responsibilities). Wraps /build with mandatory side-effects review, signal-vs-authority principle check, and artifact generation. Structural enforcement via pre-commit/pre-push hooks — the instar repo refuses commits and pushes that didn't come through this skill. NOT a user-facing skill — end users should never invoke it.
Enter autonomous development mode with STRUCTURAL enforcement. Uses a stop hook to prevent premature exit. Generates stop conditions and confirms with user before starting. Work independently for a specified duration with progress reporting.
Run any "find all instances of X" sweep — a security audit, a safety audit, a code review, a research question, a compliance check — as an iterative loop that does NOT stop at one pass. Audit → fix → RE-audit → … until a clean pass returns zero NEW discoveries. Use whenever thoroughness matters and a single pass would miss things. Trigger words: audit, sweep, find all, review everything, comprehensive, thorough, exhaustive, security review, safety audit, no stone unturned, did we get everything, convergence.
Iteratively review an instar-development spec with multi-angle internal reviewers (security, scalability, adversarial, integration, decision-completeness, lessons-aware) and real cross-model external reviewers routed through the agent's own installed CLIs (codex → GPT-tier, gemini → Gemini-tier; one pass per available family) until convergence, then produce a comprehensive ELI10 convergence report. Output is a spec tagged review-convergence — one of the two tags /instar-dev requires before it will touch instar source. NOT user-invocable; run by the instar-developing agent before any spec-driven /instar-dev work.
Establish and recover persistent agent identity that survives context compaction, session restarts, and autonomous operation. Use when an agent needs to know who it is, recover after context compression, orient at session start, or understand the identity infrastructure. Trigger words: who am I, remember, identity, after restart, compaction, context loss, who am I working with, my principles.
Schedule recurring agent tasks using cron expressions. Use when the user asks to run something on a schedule, check something periodically, automate a recurring task, set up a cron job, or wants work to happen while they're away. Trigger words: schedule, recurring, cron, every hour, every day, run daily, periodic, automated.
| title | Skill — Instar concept spec |
| slug | skill-concept |
| author | echo |
| status | converged |
| type | concept-spec |
| eli16-overview | skill.eli16.md |
| review-convergence | 2026-05-19T01:05:00Z |
| review-iterations | 1 |
| review-completed-at | 2026-05-19T01:05:00Z |
| review-report | docs/specs/reports/skill-concept-convergence.md |
| review-deviation | 6-of-7 reviewers in round 1 (Grok unavailable, no XAI_API_KEY); round 2 deferred per autonomous-mode hybrid C scope decision documented in the convergence report |
| approved | true |
| approved-by | Justin (pre-authorized 2026-05-18, autonomous-mode hybrid C) |
| approved-date | 2026-05-19 |
| approval-note | Pre-authorized auto-approval after convergence + alignment check with foundational specs (framework-functional-parity + required-primitives-inventory). Alignment verified: layered model intact (Layer 3 functional primitive with substrate dependencies on agenticSession + toolAccess + toolAllowlist declared), required-classification correct, what-is-NOT boundary respected (intent classifier kept out, MCP kept out, sandbox kept out). |
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.
| Field | Value |
|---|---|
| Layer | 3 (functional) |
| Classification | Required |
| Foundational-spec reference | specs/instar-foundations/required-primitives-inventory.md → entry #1 |
| Substrate dependencies | agenticSession, toolAccess, toolAllowlist |
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):
name that maps to a /<name> slash command AND a description short enough to fit in the model's metadata-loading budget.A Skill is NOT:
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 Claude allowed-tools frontmatter + Codex dependencies.tools mapping 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.
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.
Invariant: for every (skill × enabled-framework) pair, the rendered output must:
x-instar-stamp hash so user-edits can be distinguished from canonical drift.agents/openai.yaml).scripts/, references/, assets/) byte-for-byte (symlinks skipped to prevent tree-escape).Symmetric verify (orphan detection). The parity rule walks BOTH directions:
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-read-error).user-edit-conflict (user-edits via direct file edit are not auto-overwritten; operator must resolve).Per the foundational spec's "What is NOT a functional primitive" framing, these adjacent things are out of scope:
oneShotCompletion, not a Skill concern. A Skill's description is content the classifier reads, not classifier logic.bashExecution + toolAllowlist capabilities; a Skill just declares which tools it needs..claude/skills/<name>/SKILL.md directly, 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..agents/skills/<name>/<framework-specific>.yaml, NOT in the canonical SKILL.md.Bundled-asset rendering for icons — Codex's openai.yaml can 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.
framework-functional-parity.md: Required primitive, three-layer model honored (Skill consumes agenticSession + toolAccess substrate 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 from partial ⚠️ to native ✓ after PR #249).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, sibling openai.yaml shape, trust-level prerequisite, known quirks).src/providers/parity/rules/skillParityRule.ts — The first concrete parity rule:
js-yaml FAILSAFE schema; fail-loud on parse error.x-instar-stamp field tracking on rendered files; user-edit-conflict distinguished from canonical drift.verify(projectRoot, name) returns mismatches with reasonCode enum.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 future FrameworkParitySentinel will consume.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.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-tools rendering — lands with the Tool primitive (separate PR in the roadmap).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.
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:
js-yaml FAILSAFE schema.listOrphans() + removeOrphans() added; verify walks both directions.x-instar-stamp distinguishes user-edit-conflict from canonical drift; remediate refuses to overwrite conflicts.canonical-read-error.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).