AGENT SKILL

principle-encode-lessons-in-structure

Use when you catch yourself repeating an instruction or the user corrects the same thing again. Convert the lesson into a check that breaks on violation (a lint rule, type, runtime assertion, or script) in place of more prose.

License 许可
Apache-2.0
最近更新
2026-11-14
Stars
★ 1.6k
Forks
491

01 前言 Front Matter

name
principle-encode-lessons-in-structure
description
Use when you catch yourself repeating an instruction or the user corrects the same thing again. Convert the lesson into a check that breaks on violation (a lint rule, type, runtime assertion, or script) in place of more prose.
disable-model-invocation
true

03 SKILL.md 正文

Encode lessons in structure

A lesson that keeps coming back should be enforced by a mechanism that fails loudly when broken: a lint rule, a type, a metadata flag, a runtime check, or a script. Writing one more paragraph into an instruction file is what you do only when nothing else works.

When it applies

You notice you are writing an instruction for the second time, or the user keeps issuing the same correction. A one-off correction that has not recurred does not qualify.

What to do

  1. Ask whether the lesson can be checked mechanically. If it can, encode it. "Never log the Authorization header" becomes a logger serializer that redacts the header plus a test that fails if the raw value appears in output. "Don't call subprocess with shell=True" becomes a lint rule in CI.
  2. When the lesson depends on judgment that no check can capture, leave it as text. Move it somewhere more visible and pair it with a concrete example of the failure, so readers see what goes wrong.
  3. Once a structural fix exists, delete the duplicate instruction. The repetition was a symptom of the missing structure, and keeping both means two sources of truth that will drift.

Pick the strongest layer that can hold the rule. From strongest to weakest: an architecture in which the mistake cannot happen; type definitions, lint rules, and CI jobs; tests; and documentation last. The correct skill applies this ranking across a whole repository.

The failure it prevents

Instruction files grow until agents and people skim them, and a correction helps one run and is forgotten by the next. A check that fails the build is read every time.

Done when

The lesson is enforced by something that fails when violated, or, for a judgment call, it is prominent and illustrated with a real failure.

This differs from principle-build-the-lever, which builds tools for the current task's throughput. This principle builds guardrails that outlive the task.

Related: principle-type-system-discipline, principle-build-the-lever.

04 同仓库更多 Skills

hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-review-with-annotations

Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-find-and-synthesize-context

Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-update-docs

Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-records

Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-interactive-html

Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-collaborate-threads

Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.

★ 1.6k