Public-ready repository skill

Declarative skill authoring

Authors or revises repository skills as declarative, transferable specifications. Applies when skill metadata, What/When/Boundaries contracts, Rule declarations, optional Given/When/Then examples, conditional context, or experiment-to-helper progression needs definition.

Source and version

Repository path
.agents/skills/declarative-skill-authoring/SKILL.md
Source revision
341bceb719a28be760775b6322021d78abaa919b
Source SHA-256
153ea23114bd69f57403c548f884b5fede7f1c350d85ffadb0d4337b45ccccca
Publication standing
Public ready

Included source files

Complete skill source

The Markdown below matches the exact source text. The format link above opens the file on its own.

---
name: declarative-skill-authoring
description: Authors or revises repository skills as declarative, transferable specifications. Applies when skill metadata, What/When/Boundaries contracts, Rule declarations, optional Given/When/Then examples, conditional context, or experiment-to-helper progression needs definition.
---

# Declarative skill authoring

## Contract

- **What:** A repository skill that combines precise routing, an action-bearing core, and proportionate behavior examples.
- **When:** A recurring collaboration affordance deserves a new skill or an existing skill produces routing or workflow friction.
- **Boundaries:** Capability and transferability lead. Current user intent, available evidence, and granted tool authority govern application. Practitioner history supplies evidence and vocabulary rather than a personal profile. Scenario examples clarify behavior without implying executable coverage unless automation is explicitly present. Direct reasoning remains a valid result when a new skill would add more routing than capability.
- **Result:** A conventional `SKILL.md` with declarative third-person metadata, clear completion, and proportionate progressive disclosure.

## Rules

### Rule: Description routes by capability

The description states what the skill does and when it applies. Key trigger language appears early. Artifact, system, task, or collaborator-role nouns replace deictic persona cues.

### Rule: Contract precedes procedure

The activated skill opens with What, When, Boundaries, and Result. Rules state invariants. An operating sequence carries action when order matters.

### Rule: First receipt preserves authority

A skill offers a working method inside the current task horizon. Activation supplies conditioning and coordination while user intent, repository ground, source evidence, and granted tools retain their existing authority. The skill neither expands scope nor supplies evidence of its own effectiveness.

### Rule: Flexible body prompts reveal fit

The core contract remains compact. When interpretation benefits, the body can name **Useful when**, **Poor fit when**, **Smallest useful dose**, **Foregrounds**, **May under-attend**, **Material result**, **Interactions**, and **Rest or release when**. These are optional semantic prompts rather than required frontmatter or a second schema.

### Rule: Examples clarify branches

A scenario appears only when it changes interpretation. The smallest sufficient set often contains one ordinary or consequential boundary scenario, and many skills need none. Each retained scenario carries initial context, event, and observable result in Given/When/Then form.

### Rule: Boundary scenarios carry a return path

A consequential boundary scenario names the smallest workable recovery route or an explicit held-open state. Remaining strain stays visible. An unresolved outcome remains a question or deferred decision rather than a fabricated resolution.

### Rule: Disclosure follows need

- Metadata is always visible.
- Core contract, rules, sequence, and any retained scenarios load on activation.
- Source-specific or uncommon scenarios move into one-level-deep references with explicit load conditions.
- Deterministic scripts form after repeated mechanics demonstrate turn savings or fragility.

### Rule: Transfer remains visible

Repository and practitioner observations retain provenance, evidence class, and transfer limits. Skill names describe reusable affordances rather than individual traits.

### Rule: Composition retains distinct owners

Peer skills compose when each owns a distinct receiving result. A task-bound projection binds one source contract to a named task. Conditional context carries local detail. An interpretive lens binding can foreground a bounded perspective without gaining an independent completion claim or execution authority. The primary skill remains responsible for the receiving result, and each supporting relation carries an exit condition.

### Rule: Revision follows outside signal

Human correction, receiving-artifact behavior, an independently grounded source, a changed environment, or a materially different task can reopen authoring. Reuse counts, internal consistency, and self-authored scenarios remain routing observations. A skill can narrow, fold, rest, or retire when its material contribution moves elsewhere or its receiving job dissolves.

## Operating sequence

1. The authoring pass defines the recurring job, receiving result, and material contribution beyond standing guidance or direct reasoning.
2. A third-person description names capability and trigger territory.
3. The contract states What, When, Boundaries, and Result.
4. Non-obvious rules and an action-bearing sequence appear where order matters.
5. The smallest scenario set that changes interpretation is retained, often one and sometimes none.
6. Uncommon domain branches move into directly linked references.
7. The pass identifies poor-fit territory, interactions, and a rest or release condition when those distinctions change use.
8. Proportionate structural review accompanies inspection for personal-address, vague, and over-broad routing language.
9. Natural tasks, one near miss, and other outside signals can supply observed friction for the next revision.

## Representative scenarios

### Scenario: A new affordance has no prior skill history

- Given repeated collaboration reveals a useful named job
- And no repository skill currently carries that job
- When an initial skill is authored
- Then the first version remains instruction-only
- And scenarios appear only where intended behavior would otherwise remain ambiguous
- And every attempt supplies evidence for the next revision

### Scenario: A practitioner preference appears source-specific

- Given one practitioner corpus demonstrates a productive collaboration pattern
- When the pattern enters a repository skill
- Then the skill names the transferable affordance
- And provenance and transfer limits remain visible
- And the skill avoids constructing a personality or personalization model

### Scenario: Standing guidance already carries the job

- Given the requested result follows directly from repository ground or ordinary reasoning
- And a new routing entry would add no distinct receiving contribution
- When the authoring route is considered
- Then the no-skill path remains available
- And the observation can rest without entering the active catalog

## Conditional template

The skill loads [references/authoring-pattern.md](references/authoring-pattern.md) during creation or structural revision of a repository skill.

## Completion

Skill authoring completes when routing territory, contract, action, boundaries, transfer limit, observable completion, supporting relations, and any retained scenarios or conditional context remain legible in one pass. The next outside signal and the fold, rest, or retirement condition remain proportionate to the skill's actual receiving job.