跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
其他技能

harness-authoring

Decide where an instruction belongs and write it there, then sync and lint. Use when asked to add, change or remove a rule, skill, instruction, hook, setting or CLAUDE.md line, to "remember" something that should persist beyond this session, or when a correction should apply to future sessions.

JakeSelby · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add JakeSelby/model-citizen --skill harness-authoring

技能说明


name: harness-authoring description: Decide where an instruction belongs and write it there, then sync and lint. Use when asked to add, change or remove a rule, skill, instruction, hook, setting or CLAUDE.md line, to "remember" something that should persist beyond this session, or when a correction should apply to future sessions.

Harness authoring

Every instruction has exactly one right home. This skill finds it, writes there, and keeps the harness checkout as the source of truth for everything generic.

Find the checkout and the caller

python3 - <<'EOF'
import json, pathlib
m = json.load(open(pathlib.Path.home() / ".local/state/agent-harness/manifest.json"))
print(m["repo"])
EOF
git -C "$(…)" remote -v

If the manifest is missing, locate or install the harness before editing managed content. Do not create a second authority in a runtime configuration directory. If origin is a fork and upstream is the harness, you are a fork user. Otherwise, if origin is <owner>/model-citizen, or <owner>/agent-harness from before the rename, and you are that owner, you are the maintainer.

The ladder — first match wins

  1. Must run at a lifecycle point regardless of the model's judgment (a check before every commit, a validator after every write) → a shared policy under policy/hooks/, dispatched by lib/harness_core/lifecycle.py; native registrations belong in runtime adapters.
  2. Changes tool or editor configuration, not behaviour → an owned native setting in the relevant adapter or editor projection, reconciled by the installer. Do not add a second primitive to represent a runtime setting.
  3. True of this user only, a secret, or about one project → never the harness repo. A personal preference goes in user configuration or a custom stance root documented in docs/primitive-authoring.md; other personal guidance stays in the runtime personal file. A fact about one repo goes in that repo's AGENTS.md.
  4. A reasonable user would hold the opposite preference → a stance variant under primitives/stances/<pref>/<variant>.md, and a line in config.example.json and docs/preferences.md. Never a core rule.
  5. A procedure with steps, longer than 40 lines, or only needed on a trigger → a skill under primitives/skills/<name>/SKILL.md, with a description that says when to use it.
  6. Applies only to some kinds of file → a rule with paths: frontmatter, in the repo it applies to.
  7. Short, global, wanted on every turn → primitives/rules/<topic>.md. Check every existing rule first; the usual outcome is one sentence folded into an existing file, not a new one.
  8. Otherwise it is a memory, not an instruction → auto memory for the current project.

A "remember this" request runs the same ladder from the top. A fact about one project or one machine is auto memory for that project, never the harness. A correction to how the agent should behave anywhere is a rule or a stance, and you say so before writing it. A fact about the user is a personal file, outside the repo.

Tests to apply before writing

  • Rule or skill? Rules load every session and cost context on every turn for every user. Skills load on invocation. When a rule starts growing steps, it wanted to be a skill.
  • Core or stance? If you can imagine a competent engineer choosing the opposite, it is a stance. Licensing, commit style, testing philosophy and autonomy level are stances; "verify before you claim it works" is not.
  • Does it duplicate a global rule? Grep primitives/rules/ and primitives/stances/ for the topic. Do not restate a policy that lives in a global rule inside a project rule; link it.
  • Is it generic? No names, no paths under a home directory, no employer, no project. The lint will reject it anyway; write it in second person from the start.

Write, sync, lint, commit

  1. Edit shared sources in the isolated development checkout. Runtime directories contain managed links and generated views; editing them can change the live checkout or create drift.
  2. Run bin/harness generate for native views and bin/harness generate --check to verify them. See docs/primitive-authoring.md for custom dimensions and native bindings. Verify sync in a disposable home with HARNESS_HOME, CLAUDE_CONFIG_DIR, and CODEX_HOME redirected. Sync normal installations from the reviewed release, not the development worktree.
  3. bin/harness lint — fails on personal strings and secret patterns.
  4. Commit with a Conventional Commit. Then, by who you are:
    • Maintainer: every change goes on a branch in a worktree and opens a PR; the main ruleset requires green checks and a squash merge. Code changes (bin/harness, shared policy, tests) carry a test; content changes are gated by the lint and review.
    • Fork user: commit to your fork's main, which is your live harness. If the change is worth sharing, git fetch upstream && git rebase upstream/main, push a branch to the fork, and gh pr create --repo <owner>/<name>, naming the repository your upstream remote points at.
  5. Record in one line where the item went and why, so the placement is auditable.

Writing rule and comment text: the conciseness examples

conciseness.md was cut to its operative lines when the always-loaded context was capped. Its worked examples live here.

Explain a decision once. Pick the single most natural home for a design rationale — usually the module or class docstring where the thing is defined, or the user-facing doc page for anything a user needs. Every other file that touches the concept gets a short pointer back, not a restatement.

# Bad — restates the full rationale in a consuming file
# We chunk at 999 rather than the documented 10,000 limit because early testing
# suggested the endpoint became unreliable above 1,000 records, and because ...

# Good — one line, 
阅读完整来源 ↗