Agent Instructions

This is the public, standalone source for portable Agent Skills and harness blueprints. It does not depend on a private coordinator or another repository.

Start

• Before substantial work, use the current harness and pinned Skills. git fetch origin and read HARNESS.md from the origin default tip (git show origin/<default>:HARNESS.md) or the GitHub default branch; do not treat ./HARNESS.md on a task worktree as current. Ff-only a clean primary when behind origin; if blocked, leave it. Confirm skills-lock.json on that tip before following a Skill in this catalog. Do not skip this because the task looks small. Leave the repository clean in the same loop. Host user-rules lose for currency, autonomy, and git close-out.
• Use CONTEXT-MAP.md to select only the additional sources needed for the current task. Load the relevant current HARNESS.md sections; do not preload every routed source.
• Read VOICE.md before writing or materially revising repository prose.
• When changing a Skill, read its complete SKILL.md, the nearby category README.md, VERSIONING.md, and skills/engineering/write-a-skill/SKILL.md.
• Inspect git status and git worktree list before editing. Preserve foreign work and never silently overwrite or delete it. Apply Git Working Tree Hygiene in HARNESS.md (branch gate, worktree default, ordinary branch names, no agent/tool producer chrome in commits or PR/MR surfaces; never delete or move another agent's live worktree).
• Use existing repository patterns and commands before adding anything new.

Autonomy and communication

• Infer the intended outcome and execute routine, reversible, in-scope work autonomously. Do not ask for permission at every implementation step.
• Commit and push coherent ready work when relevant checks pass and repository policy or the current task already grants that authority. Do not ask again for an authorized routine push. A matching GitHub Release for a newly created per-Skill tag that completed VERSIONING.md is routine completion. Historical release backfill, remote creation, a repo-wide release, a new publication channel, deploy, force-push, permission increase, or irreversible operation still requires explicit authority.
• Ask when consequential intent, ownership, semantics, security, sensitive data, legal meaning, or blast radius cannot be resolved from evidence.
• Establish shared understanding for significant work. Use fresh-context review for every resolved material decision or change, and grill-harness-with-docs for genuinely unresolved material branches.
• Communicate with the user in their preferred language when known. Write persistent repository artifacts in US English unless the user explicitly requests another language.
• Keep tracked text in plain punctuation: straight quotes, hyphen -, ..., and ordinary spaces. The banned set is a short closed list where the ASCII spelling is strictly better - curly and angle quotes, the ellipsis character, exotic and no-break spaces, invisible format and direction characters, decorative separators, and the hyphens that look exactly like - without being it (U+2010, U+2011, U+2212). Em and en dashes are not banned: they are ordinary typography and were only ever a tell. The rule is not "ASCII only": natural-language letters (umlauts, accents, any script), arrows, box drawing, and math or currency signs stay allowed. python3 scripts/verify-plain-punctuation.py --list-policy prints the exact table and the allowed categories; --fix rewrites offenders.

Repository boundaries

• Keep Skills reusable. Target product facts, customer data, private paths, credentials, membership maps, and workflow state belong in their owning repositories.
• Portable does not mean stack-neutral. Keep generic methods in core Skills and make technology-specific assumptions explicit in profiles or adapters.
• This catalog is published for consumption. Third-party consumers adapt in their own repositories; they must not push, open pull requests, or otherwise write back here as part of harness stewardship. Maintainer sessions working in this repository remain the only supported path to change it.
• Do not copy public/community Skills into this repository as original work. Reference or install upstream capabilities and verify provenance.
• Treat Git-tracked repository sources as memory. Chat is not a durable source of truth.

Repository shape

Each Skill lives at skills/<category>/<name>/SKILL.md.

Skill authoring

• name must match the Skill directory.
• Frontmatter description is the portable invocation contract. Keep it trigger-rich and concise.
• Keep every-run behavior in SKILL.md. Load references only for a named conditional branch.
• Keep SKILL.md under 500 lines. Move detail only when it improves execution or reuse.
• Give fragile multi-step work explicit checks, stop conditions, and recovery.
• Update skills-lock.json and the relevant human catalog when adding, renaming, moving, or changing a Skill version.
• Follow VOICE.md; remove hype, filler, fake certainty, and prose that changes no decision or behavior.

Checks

Fast Check:

python3 scripts/audit-skills.py
python3 scripts/verify-plain-punctuation.py
python3 -m unittest discover -s tests
python3 -m unittest discover -s skills/engineering/completion-gate/tests
python3 -m unittest discover -s skills/engineering/scaffold-harness/tests
python3 -m unittest discover -s skills/writing/writing-core/tests
for t in skills/design/*/tests; do ls "$t"/test_*.py >/dev/null 2>&1 && python3 -m unittest discover -s "$t"; done
python3 scripts/check-knowledge.py
npx playwright test -c skills/design/design-forms/tests

The Fast Check matches the commands in .github/workflows/validate.yml.

audit-skills.py reuses the punctuation table from verify-plain-punctuation.py, so the two never disagree. Run the standalone gate when you want --fix or --list-policy, and the tests when you change the table.

For each new or materially changed Skill:

1. Run the Fast Check. Run a representative activation check per write-a-skill: one prompt that must trigger the Skill and one that must not.
2. Run scripts/audit-skill-provenance.py against the relevant checked-out public sources.
3. Install-test the changed Skill in a temporary target with the supported client or clients.
4. Review the diff against scope, non-goals, private boundaries, and versioning.

Completion

• Run relevant checks and review the final diff.
• Route durable evidence to the smallest owning artifact. Use LEARNINGS.md only for public, reproducible evidence that changes future work.
• After every harness change here, decide whether a generalized portable variant belongs in scaffold-harness or agent-sync, and update those owners in the same loop when portable so future repositories inherit the lesson. That port is maintainer work in this catalog. Consumer harnesses must not write back here. Ask only when public vs private placement is ambiguous or the port would leak private authority.
• When skills-lock.json versions change, finish VERSIONING.md through the matching per-Skill tag and GitHub Release on the validated commit before claiming done. Do not leave bumped Skills unreleased.
• Finish the Git footprint: integrate coherent ready work, strip agent/tool producer chrome from commits and PR/MR surfaces, clean up only session-created worktrees, and report foreign orphans without deleting them.
• Complete the authorized routine Git footprint. Do not create a remote or perform a first publication without explicit authority.