Skill Architect

Architect portable, high-quality agent skills from a vendor-neutral perspective. Use this skill as an independent planning, creation, review, refactoring, comparison, distillation, reconciliation, and teaching layer for any agent skill repository or runtime.

Why this skill exists

Several high-signal upstream skills overlap while emphasizing different strengths:

Treat the Agent Skills specification as the portable syntax baseline, then use this skill as a quality and governance synthesis: it directs, plans, and reviews skill work at the architecture level, then routes into source-specific, project-specific, or repository-specific details only when needed. Concrete examples of this rubric in practice can be inspected across the skills4sh skills.

Operating mode

Start with the current working context, not an upstream rubric. Check the CWD, project files, installed skill location, or repository convention first. Use the Agent Skills specification for portable baseline syntax; external rubrics inform content quality, while local rules win on accepted frontmatter fields, manifests, lockfiles, CI, and release gates. Do not add experimental allowed-tools unless the target runtime and repository schema both accept and enforce it.

Use this order:

1. Classify the request — choose plan, create, audit, fix, refactor, compare, distill, reconcile, or teach before deciding files or checks.
2. Read the local standard — find the CWD/project/repository authoring standard, agent instructions, check commands, and target skill before editing.
3. Select the lens — structure, quality/evals, vendor compatibility, distribution governance, or predictability.
4. Run the predictability pass — check invocation fit, branch uniqueness, information hierarchy, completion criteria, leading words, duplication, sediment, sprawl, no-op lines, and premature-completion risk before proposing edits.
5. Plan the artifact — decide the portable core, references, optional assets/scripts, vendor metadata, and validation path.
6. Patch narrowly — avoid churn-only rewrites; improve only the requested surface and directly related standard violations.
7. Verify mechanically — run repo checks or the closest local equivalent before handing back.

Command modes

Use command-like modes when the user names one explicitly. If no mode is named, infer the closest mode from the request and state the assumption.

Mode rules

• Plan before non-trivial multi-file changes, new gates, release work, or cross-vendor adapter changes.
• Create should start from concrete use cases, then draft the portable core before vendor metadata.
• Audit is read-only by default; present findings and wait unless the user also asks to patch.
• Fix is deterministic and dry-run-first; only apply fixskill.py --write for safe mechanical edits, then run validateskill.py.
• Refactor preserves intent; do not rename, split, or change behavior beyond the requested scope without calling it out.
• Compare must cite inspected sources and separate source facts from adoption decisions.
• Distill must separate session-specific events from reusable patterns, cite the session source, and propose a skill only from repeated or high-value behavior.
• Reconcile must verify whether prior plans, findings, and proposals still match the current context; retire fixed or rejected items instead of re-reporting them.
• Teach should explain the smallest useful rule, then give one concrete example rather than dumping the whole rubric.

Skill architecture workflow

1. Gather concrete use cases

Capture only the details that determine structure:

• exact user phrases that should trigger the skill
• file paths, tools, APIs, or error messages that imply the skill
• repeated task shape: quick reference, workflow, router, review rubric, or deterministic helper
• target runtimes: Claude, Codex/OpenAI, Craft, Cursor, Antigravity, Azure/Copilot-style agents, or generic file-reading agents
• whether the skill needs references, assets, examples, or helper scripts

Ask one focused question if a structural choice is ambiguous. Otherwise infer from the CWD/project/repository pattern and state the assumption.

2. Separate portable core from adapters

The portable core lives in SKILL.md and linked references. Vendor details live in adapter sections or metadata files.

Use this split:

3. Draft with progressive disclosure

Keep SKILL.md focused on routing and immediate behavior. Move long comparisons, advanced examples, vendor matrices, and eval details to references/.

Minimum portable skill shape:

skills/<skill-name>/
├── SKILL.md
├── LICENSE
└── references/          # only when detail would bloat SKILL.md

Add assets/ or helper scripts only when they materially improve repeatability. Treat scripts as inert skill assets unless the local project or runtime explicitly allows executable helpers; document, link, hash, and security-scan them according to local conventions when available.

4. Review before patching

Prepare a compact audit packet before making non-trivial edits:

Run a predictability and pruning pass before judging style or patching content:

1. Invocation fit: decide whether the skill should be model-invoked or user-invoked. Pay context load only when autonomous agent reach or cross-skill reach is necessary; recommend a router skill when many user-invoked skills create cognitive load.
2. Description branches: keep one trigger per real branch, remove synonym-only trigger duplication, and front-load strong leading words that also appear in prompts, docs, or code.
3. Information hierarchy: classify each major block as step, in-skill reference, or disclosed reference. Inline what every branch needs; move branch-only detail behind a context pointer.
4. Completion criteria: every ordered step should end with a checkable done condition. Sharpen vague criteria before splitting a sequence.
5. Premature-completion risk: if visible post-completion steps pull attention forward and the current criterion cannot be sharpened further, recommend a real context-boundary split.
6. Leading words: replace repeated explanatory prose with a compact pretrained concept only when it improves predictable execution or invocation.
7. Pruning: apply sentence-level relevance and no-op tests; remove duplication, sediment, and sprawl instead of polishing dead prose.

For behavior-shaping skills, add at least one forward test or prompt scenario. For any shipped CI, shell, or code — helper scripts, snippets, or workflow examples — review it for functional correctness and execute it against a fixture rather than vouching for it by reading. Reading alone routinely misses logic defects (wrong regex, broken cascade handling, crash-after-success) that a fixture run surfaces immediately; security-scanning and shape-checking do not cover correctness. An audit is incomplete until each embedded-code finding or pass includes a fixture command plus observed output, or an explicit skipped-risk note.

Use a bounded executable-surface triage before invoking a full code-review lens. Check whether the artifact has: fixture coverage for shipped scripts/snippets, fail-closed error handling, shell/runtime portability, pinned or cached external tools, path and quoting safety, network/credential boundaries, parser edge-case tests, and CI visibility. Report these as skill-architecture risks with evidence and a verification path; route algorithmic correctness, exploitability analysis, performance tuning, or large refactors to a dedicated code-review skill instead of expanding this skill's scope.

For eval and adapter claims, calibrate the finding to local policy and evidence quality: prompt-only eval catalogs are useful retrieval vectors but incomplete evidence for high-risk behavior claims, and missing vendor adapters are packaging defects only when the local repo requires them. Weak descriptions are deterministic failures only when the rule is portable and low-false-positive; in skills4sh, generic trigger-only wording such as Use when creating skills. fails mechanically.

For test vectors, harness setup, enumeration consistency, and severity calibration, use [Eval methodology](references/eval-methodology.md) and [Portable rubric](references/house-rubric.md) rather than expanding SKILL.md.

5. Make handoffs executable

When producing a plan, proposal, audit packet, or distilled skill spec for another agent or a future session, write for the weakest plausible executor. Include exact paths, relevant excerpts, local conventions, scope boundaries, verification commands with expected results, drift checks when source state matters, and STOP conditions for mismatches.

Record rejected findings or non-adopted patterns with one-line rationales so they do not return in the next audit or reconciliation pass.

6. Verify and hand off

Run the narrowest meaningful checks for the current working context. Prefer documented validation commands, CI gates, evals, fixture tests, hash checks, and security scans when present.

For skills4sh examples, the usual checks are:

npm run check:skill-standard
npm run check:drift
node bin/hash-check.mjs
npm test

Run a focused or full security scan when new files contain scripts, shell examples, credentials guidance, network examples, or other security-sensitive patterns.

Report exactly what passed, failed, or was skipped. Do not claim an eval, scan, or fixture test that was not run.

Helper scripts

Optional helper scripts live under assets/scripts/ so they ship as inert skill assets:

Read or run scripts only when the task needs deterministic inspection or scaffolding. Local validation commands and CI, when present, remain the source of truth.

Deterministic checks vs judgment

Skill work splits across three layers — keep them separate and route each check to the layer that can decide it:

The litmus test: if a script can decide it, automate it; if it needs reasoning or taste, it stays in the rubric. When a local binding gate exists, it wins over the portable validator on any overlap. The portable validator is deliberately narrow: it checks only facts visible inside one skill folder. Codifying a rule (for example a numeric size band) moves it from judgment toward the validator; treat that as the goal, not a loss.

Reference files

Non-negotiables

• Do not make a vendor-specific skill the portable rubric verbatim.
• Do not reinstall upstream skill-creator over an existing skill without checking provenance and collision risk.
• Do not ship loose summary-only descriptions; the description must include a concise capability clause and concrete trigger/use conditions.
• Do not add unlinked reference files.
• Do not add helper scripts without a concrete repeatability benefit and a validation path.
• Do not treat skills.sh popularity as quality proof; inspect source, tests, security posture, and portability.