Skill Engineering

Skill Engineering

Principle expression

Primary: P16 Supporting: P09, P08, P15

Scope

Engineer an agent-facing expression only when an observed action gap recurs and a reusable skill is the smallest form that can close it. The objective is not a well-formatted prompt; it is an agent that can make the intended judgment and take the intended action under its real context constraints.

Do not create a skill for a one-time request, a vendor command reference, an implementation detail, or a behavior already owned by a more specific skill. Use a project document, command, reference, or local adapter when that is the truer form. Do not create, interpret, or revise Sequence entries here; route a possible new principle to principle-cultivation.

This package is independently usable. It carries a read-only Sequence snapshot in references/sequence.md and source-bound interpretations under references/sequence-interpretations/. The package is a portable lineage baseline, not a second semantic source.

Dispatch

• With create, read and follow commands/create.md.
• With rewrite, read and follow commands/rewrite.md.
• With review, read and follow commands/review.md.
• With test, read and follow commands/test.md.
• With refresh-sequence, read and follow commands/refresh-sequence.md.
• With sync-sequence-snapshot, read and follow commands/sync-sequence-snapshot.md.
• With no argument, diagnose the stated agent-action gap, choose the smallest truthful form, and then use the matching path above.

Principle source resolver

Resolve the target's lineage before selecting an expression team.

1. If the host project contains principles/SEQUENCE.md and its corresponding interpretations directory, treat that declared local source as authoritative for the current task.
2. Otherwise use this package's references/sequence.md and only the selected files under references/sequence-interpretations/. This fallback must be sufficient for offline use.
3. If freshness materially affects the decision, use refresh-sequence to obtain a temporary, verified remote comparison. Never overwrite the packaged snapshot from a task run. If refresh fails, continue with the baseline and report its version rather than inventing a current result.

When host and packaged lines differ, use the host source for its project and report the lineage difference. Do not merge, edit, or silently reconcile them.

Core method

1. Ground the action gap. State who must act, the concrete action or judgment that currently fails, the source evidence, and the observation that would show improvement. Do not begin from a skill name or a preferred file layout.
2. Form the target expression team. Resolve the Sequence through the source resolver, then read only the interpretations for nominated P-IDs. Select exactly one Primary and at most three Supporting P-IDs for the target expression only after the concrete action gap and its governing relation are formed. Record why each changes the core method and why an existing skill cannot own the same gate. Remove a P-ID whose contribution does not survive into the method. Use references/expression-team.md. If the host has a human-nominated alternate candidate, keep it outside this lineage and add it only as a separate, temporary trial with an explicit baseline, candidate delta, and disconfirming observation.
3. Choose the minimum form. Prefer an existing skill, a command, a reference, or a project-local adapter when it already enables the action. Create a new skill only when it has a distinct repeated trigger, judgment, and durable artifact or decision gate. Treat a request for a new runtime check, lifecycle, registry, queue, role, retry path, or projection as a separate mechanism question. First record the observed action gap, the existing method/context/task-shaping/policy response, the hard property that fails, its current owner, and the smallest probe that distinguishes method failure from mechanism failure. If the existing base preserves the hard property, keep the repair in this expression layer; only route to mechanism design when a real lifecycle, effect, permission, concurrency, recovery, or evidence invariant fails.
4. Make the expression actionable. Put stable trigger and scope signals in frontmatter; put the active judgment and short work loop in SKILL.md; put volatile detail, variants, and long protocols behind direct references. Use references/expression-layers.md for register, doctrine-file shape, and P16 probes. Domain skills own organizational or methodological doctrine; this skill owns how that doctrine is expressed. Compose the prompt around the actor's object, governing relations, decision, and evidence path. A role name, qualifier, repeated prohibition, or method step earns its place only when it changes what the Agent notices, preserves, decides, or verifies; do not mistake professional-sounding predicates for an activation method.
5. Test behavior, not prose. Define a task that would reveal the intended behavior, a boundary task that should not trigger or should route elsewhere, and the evidence each outcome must provide. When claiming improvement, use a comparable baseline or label attribution unproven. When the claim concerns prompt expression itself, isolate the proposed carrier through predicate, composition, or order ablation; use matched natural-language conditions for every language covered by the claim. Use references/evaluation.md. Revise from observed failure rather than from aesthetic preference.
6. Commit the smallest valid expression. Preserve source links and record remaining uncertainty. In source-bearing research, interpretation, proposal, or review artifacts, keep descriptive inline links on the claims they support; a detached bibliography alone is insufficient. A passing format check proves only structure; do not claim behavior improvement without behavior evidence.

Operating boundaries

• This skill's P16/P09/P08/P15 team governs the engineering process. Every target skill forms its own selected expression team; do not copy this team's P-IDs into the target by default.
• An expression team is not a principle-review committee. It has no vote and no authority over the Sequence.
• A nominated alternate candidate is not a P-ID expression member. Never place it in Primary or Supporting, let it lead the target, or package it into a standalone skill snapshot. At most one may participate in a host-local trial; route the result back to principle cultivation.
• Do not turn a successful local prompt into a general rule without a second context or a failure boundary.
• When a project-wide agent-work failure has not yet been localized to a skill, let an agent-workflow diagnostic owner identify the surface first when one is available. Once evidence selects skill trigger, expression, context layering, or behavior evaluation, this skill owns that work; do not keep both methods as parallel coordinators.
• Keep the review surface small enough for a human to inspect: target action, selected P-IDs, trigger/boundary, test evidence, and the changed files.

Completion standard

Treat a skill change as ready only when it has a valid trigger description, a selected expression team, an explicit non-scope, a layered context shape, and evidence from an appropriate scenario. If one of these is absent, leave the skill as a proposal or report the gap instead of asserting that the agent will perform better.

When a nominated alternate participated, readiness also requires a separately labeled trial result. A successful skill does not by itself prove the candidate caused the success; report overlap or inconclusive unless the baseline comparison isolates its decision delta.