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.

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 fix_skill.py --write for safe mechanical edits, then run validate_skill.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.

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. Done when one mode is named or the inferred mode is stated as an assumption.
2. Read the local standard — find the CWD/project/repository authoring standard, agent instructions, check commands, and target skill before editing. Done when the governing standard and check commands are cited by path, or their absence is stated.
3. Select the lens — structure, quality/evals, vendor compatibility, distribution governance, or predictability. Done when each lens in scope is named.
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. Done when each check has a keep/patch decision with file:line evidence.
5. Plan the artifact — decide the portable core, references, optional assets/scripts, vendor metadata, and validation path. Done when every file to add or change is listed with the command that will verify it.
6. Patch narrowly — avoid churn-only rewrites; improve only the requested surface and directly related standard violations. Done when the diff touches only planned files, or each extra file is called out.
7. Verify mechanically — run repo checks or the closest local equivalent before handing back. Done when each check is reported as passed, failed, or skipped with its exact command.

Skill architecture workflow

1. Gather concrete use cases

Capture only the details that determine structure:

• exact request 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 runtime capabilities: check required tools, permissions, and instruction loading; use vendor-adapters.md when host-specific execution or packaging details matter
• 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 — execute it against a fixture rather than vouching for it by reading; reading and security scans miss logic defects such as a wrong regex. An audit is incomplete until each embedded-code finding or pass includes a fixture command plus observed output, or an explicit skipped-risk note.

Run the bounded executable-surface triage and calibrate eval, adapter, and weak-description findings with the review rubric; route algorithmic correctness, exploitability, performance, and large refactors to a dedicated code-review skill.

Authors/reviewers evaluating Skill Architect itself only: skip this catalog when using Skill Architect for another task. The mode scenario catalog supplies self-contained fixture files for all nine modes, isolation instructions, grading criteria, and description-only routing prompts. Materialize a fresh case directory and withhold grading from the executor; the catalog is test input, not evidence that those modes passed.

For test vectors, harness setup, enumeration consistency, and severity calibration, use Eval methodology and Portable rubric 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. Reference accessible authoritative artifacts with exact paths or URLs; include essential excerpts only when the executor needs them. Preserve local conventions, scope boundaries, verification commands with expected results, drift checks, and STOP conditions. For dependent tasks, specify consumed/produced interfaces and requirement coverage using the handoff plan rubric.

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. In skills4sh, run the packaging check list.

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:

inspect_skill.py and validate_skill.py each accept one skill folder per invocation. For multiple skills, invoke each helper separately for each folder; reuse the same Python environment.

Validation and inspection need Python >=3.10 plus the hash-pinned Python dependency file in an isolated runner: run_uv.py first, a temporary virtual environment as fallback, with every helper run as python -E -B. Never install validation dependencies into the global Python environment, and do not use python -I. Use the helper runtime for exact uv, venv, and PowerShell commands and for when to report a helper unavailable.

Scaffold and fix helpers need only Python. The fixer accepts column-zero literal mapping keys and simple single-line literal names; it refuses unsupported key or name syntax before any edits. Use manual review for those cases, then validate.

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 four 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.