harness
Use when adding, changing, removing, testing, packaging, or evaluating any surface of the Pi agent harness — Agent Skill, extension-owned tool or command, provider, lifecycle hook, TUI, prompt template, theme, package, SDK/RPC integration, standalone CLI — when a requested capability needs classification among them, or when changing harness rules and shared contracts. Also use when a request opens harness inspection or improvement without naming the change, or when harness work is delegated across workers or sessions. New enumerated surfaces require authority before they land; apply the universal Intent authority rule before asking for approval. Reclassifying an addition does not supply authority. Do not use for invoking or installing an unchanged resource, ordinary application code, unrelated uses of "tool", "skill", or "extension", or Pi core development.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- harness
- description
- Use when adding, changing, removing, testing, packaging, or evaluating any surface of the Pi agent harness — Agent Skill, extension-owned tool or command, provider, lifecycle hook, TUI, prompt template, theme, package, SDK/RPC integration, standalone CLI — when a requested capability needs classification among them, or when changing harness rules and shared contracts. Also use when a request opens harness inspection or improvement without naming the change, or when harness work is delegated across workers or sessions. New enumerated surfaces require authority before they land; apply the universal Intent authority rule before asking for approval. Reclassifying an addition does not supply authority. Do not use for invoking or installing an unchanged resource, ordinary application code, unrelated uses of "tool", "skill", or "extension", or Pi core development.
- compatibility
- Pi-specific workflow. The bundled skill validator uses dependency-free TypeScript and requires Node.js 22.19 or newer for direct execution; verify Pi-sensitive behavior against the active Pi installation. Uses the sibling repository instructions at `../../AGENTS.md` for the owning repository's binding rules and `../../extensions/` for extension telemetry source contracts. References `../delegate/SKILL.md` for operator status reports.
02 资源文件 16
- 参考文档references/calldiff.md6.0 KB
- 参考文档references/collaborative-work.md6.3 KB
- 参考文档references/extension-audit.md4.5 KB
- 参考文档references/extension-engineering.md14.1 KB
- 参考文档references/extension-research.md7.5 KB
- 参考文档references/extensions.md6.2 KB
- 参考文档references/pi-grounding.md3.9 KB
- 参考文档references/removal.md3.8 KB
- 参考文档references/skill-design.md8.3 KB
- 参考文档references/skill-evaluation.md6.1 KB
- 参考文档references/skill-research.md7.7 KB
- 参考文档references/skills.md7.6 KB
- 参考文档references/surface-selection.md5.0 KB
- 参考文档references/verification.md8.1 KB
- 脚本scripts/validate-skill.mts32.6 KB
- 脚本scripts/validate-skill.test.mts17.7 KB
03 SKILL.md 正文
Harness
Select, design, change, and verify Pi harness surfaces through one entry point. The requested capability is the subject; skills, extensions, prompts, packages, and external integration modes are implementation lanes selected after the outcome is understood.
Core contract
- Preserve the operator's fixed outcome, artifact, destination, and explicit architecture. Research only genuinely open choices.
- Read collaborative-work.md when the request opens inspection or improvement without naming the change, or when work spans workers or sessions. Use it to select the source scope and work method, not to require delegation.
- Classify the capability before drafting when the implementation surface is open. A user word such as “tool,” “command,” or “plugin” does not settle the Pi building block.
- Use the lowest sufficient surface, but build a coherent end-to-end capability rather than minimizing line count.
- Treat current Pi documentation, declarations, installed source, and shipped examples as the authority for version-sensitive claims.
- Follow the owning repository's rules in
AGENTS.mdfor provenance, privacy, worktree, testing, release, scope, and dependency approval. - Keep common decisions here and lane-specific detail in one-level references. Read only the references that the selected lane requires.
- New surfaces require authority before they land. A private prototype needs none. Apply the approval gate below. The enumeration decides what counts, not the agent's framing of the request.
New surfaces require authority
A change adds a new surface when it introduces any of the following that do not already exist in the repository:
- A new top-level directory (other than ignored tooling such as
node_modules/.git). - A new extension slice directory under
extensions/. - A new skill directory under
skills/. - A new prompt template file under
prompts/. - A new theme file under
themes/. - A new application directory under
config/. - A new non-test script under
scripts/. - A new
package.jsonscriptsentry. - A new key under
package.jsonpi(for examplepi.prompts).
Edits, tests, docs, and refactors inside an already-registered surface are ordinary work. They still need surface classification and proportionate verification, but they do not need a new-surface proposal.
Private prototypes
An agent may build a new surface and run it in a trial (repository-root path docs/conventions/worktrees.md, section "Trial") without prior approval when all of these hold:
- the files sit in a branch worktree or working directory that no Pi settings entry loads, and nothing lands on
main; - the work adds no dependency, uses no credential, and writes to no live store; and
- the result states the exploratory question that the prototype answers.
A prototype is evidence for a proposal, not an adopted surface. Landing it follows the approval gate below. Remove a prototype that is not adopted.
Approval gate before landing
When the intended change lands a new surface on main:
- Apply Intent authority in the universal
AGENTS.md. Determine whether the supplied authority covers the surface or delegates its selection. Apply any workflow-specific grant under the repository's authority rules. An operator request that names the surface already satisfies this gate. - Establish the required warrant under workflow step 3. Name each new surface against the enumeration, the nearest existing surface and why it cannot absorb the change, the lowest sufficient layer, and out-of-scope items. A warrant establishes suitability, not authority.
- If authority is missing, stop before landing. Propose the complete change in chat, with the runnable prototype when one exists, and wait for explicit operator approval. Without a grant that delegates surface selection, approval must cover the surface itself, not only the desired outcome. Do not recreate this hold when step 1 already establishes authority.
- Land only the authorized scope. State the warrant in the result when no approval request was needed.
If an unapproved new surface is already present on main when you notice it, stop, report what is present, and hold for operator disposition. Do not silently keep expanding it or silently revert concurrent work you did not author.
No backward compatibility
This harness is built and operated by one party with no external consumers, so every surface implements only the current contract. Do not carry predecessor behavior: no compatibility shims, schema migrations, dual read/write paths, deprecated field aliases, legacy-record normalizers, or fallback readers for retired shapes. Delete superseded machinery across code, tests, current docs, prompts, and review checklists rather than renaming "legacy" while keeping the mechanism.
Contracts that remain valid are current, not historical:
- Honor the current Pi API and version-declared behavior, and the current public contracts a surface ships.
- Data the harness produced under an older shape has no standing guarantee of readability. If a change breaks existing artifacts, the operator decides at that point whether to migrate, discard, or leave them unreadable.
- Tolerant validation of malformed current data is corruption containment, not predecessor-schema support; keep it without interpreting retired field names or reconstructing old behavior.
- Historical design records may describe superseded systems as history; they do not authorize compatibility code.
A genuine one-time migration requires explicit operator direction from concrete data and consequence. Do not infer one from files merely existing on disk.
Operator-facing diagrams
Use Pi's native Mermaid rendering without an operator prompt when relationships are easier to understand visually: component or call flow, lifecycle sequence, state transition, ownership boundary, or before/after structure. Emit a compact top-level Mermaid block and pair it with the short conclusion it supports. Use the installed renderer's flowchart, sequence, state, class, or ER forms. Prefer top-to-bottom layouts and short labels so Pi renders within terminal width; simplify or split a diagram before it falls back to source.
Do not paste a long tool transcript into chat. When a tool returns a purpose-built structural view, preserve its native shape and trim it to the load-bearing region; do not flatten it into a table or redraw it in Mermaid. Otherwise, preserve the raw result in the tool record and translate only the load-bearing structure. Use prose or a table when sequence or relationships are not the point. A diagram explains evidence; it does not replace the sources or observations that establish the claim.
TypeScript call-structure evidence
Use calldiff when a material question concerns who calls whom and its structural view can answer that question. A TypeScript edit alone creates no obligation to run it. Read calldiff.md for invocation and limits. Reuse applicable output; repeat the analysis when relevant changes invalidate it.
calldiff is syntactic, not a typechecker or runtime observation. Behavioural claims need appropriate evidence at their own layer, including applicable existing results. A calldiff invocation does not independently create a test obligation.
Workflow
1. Reconstruct the contract
Derive the requested outcome, acceptance, and granted permissions from the request and established sources. Separate operator directions and binding rules from agent interpretations, including inherited plans. Record only the fixed decisions, open choices, target, and release constraints that affect execution. Apply Intent authority in the universal AGENTS.md to handovers and delegated task contracts.
Before designing a capability, search operator memory and read matching notes for standing operator decisions about that capability. Apply those decisions within their original scope under the current request and instructions.
Use the Pillars consultation procedure for corrections: Corrected-Assumption Leakage governs a corrected factual premise; Frame Abandonment governs a rejected interpretation. Carry the resulting changes into affected work rather than asking the operator to specify the outcome again.
Complete when: named sources support the outcome and permissions, interpretations remain revisable, and no open question asks the operator to repeat a settled decision.
2. Select the surface
Read surface-selection.md when the artifact type is open, ambiguous, cross-resource, or disputed. Name both the primary capability surface and any separate distribution surface. Do not flatten extension-owned tools, commands, providers, events, and UI into peers of extensions.
Complete when: the selected surface follows from the outcome and current Pi contracts, not from the first noun in the request.
3. Establish the warrant when required
A suggestion is not a surface. Naming a useful tool, skill, or integration in chat is always free — no warrant, no approval.
Warrant and approval are separate. The warrant is the content of a proposal; it does not grant write authority. New-surface approval is governed by the approval section above.
Evidence warrant
Correct capability classification decides which case applies; authority exemptions remain separate. Choose one case.
- Correctly classified agent-proposed skill. A usefulness rationale — the capability it provides and why it is worth having — is sufficient. No observed failure, measured omission, structural evidence, or binding requirement is needed.
- Any other agent-proposed new persistent surface, recurring mechanism, guard, high-frequency context producer, or shared service. A grounded basis is required: an observed failure with meaningful cost; a reproducible local omission or measured opportunity; direct structural evidence of a missing capability or inaccessible information; or a binding security, privacy, current-host compatibility, or platform requirement.
Caliber for repeated or hard-to-remove mechanisms
Applies in addition to whichever evidence case governs, for any agent-proposed mechanism paid repeatedly or hard to remove, regardless of the surface it is implemented through. A recurring skill carries both the skill evidence case and this overlay.
The proposal also carries the caliber fields: estimate its normal fire rate and operating or context cost, state the observable behavior it changes, name an owner and evaluation point, define removal conditions, and explain why the expected cost is proportionate and how the intervention is bounded or reversible.
Every required warrant states its capability, the nearest existing surface and why it cannot absorb the change, and the lowest sufficient layer. Caliber facts inform the operator when approval is required and guide proportional design in all cases; they do not recreate an evidence prerequisite or create a separate approval gate. Caliber alone is not an independent refusal gate. The agent recommends the lowest-cost coherent design.
Classification cannot be changed to obtain the skill rule. A capability that requires scheduling, event interception, or deterministic enforcement is not a skill and takes the non-skill rule regardless of what it is called.
No warrant is needed for a fixed repair, an operator-selected outcome or architecture, ordinary maintenance, a removal, or a documentation/test correction that preserves an established contract; those still require surface classification and proportionate verification.
Rationale (auditability, not operative): the skill rule is a bounded, operator-approved exception to this workflow’s evidence gate for other agent-proposed surfaces and mechanisms. Harness Over Architecture also permits a grounded exploratory question to warrant a bounded capability probe; this workflow retains its narrower evidence gate for other agent-proposed surfaces and mechanisms. The skill exception is evidentiary only; the retained requirements above implement the pillar's nearest-surface, reversibility, and skill-sprawl guidance, against which the exception remains auditable.
Complete when (warrant classification/content only; approval is gated by the approval section, not retested here):
- no suggestion was mistaken for a surface;
- no agent-proposed skill was withheld for lack of an incident, measured omission, structural evidence, or binding requirement;
- every warrant-required non-skill surface or mechanism carries a grounded basis;
- every agent-proposed mechanism paid repeatedly or hard to remove carries the caliber fields;
- every required warrant states its capability, nearest existing surface, and lowest sufficient layer.
4. Load one implementation lane
- Agent Skill: read the Agent Skill lane. For a new skill or substantial redesign, also read skill-research.md, skill-design.md, and skill-evaluation.md only as their gates require.
- Extension or extension-owned surface: read extensions.md. Pull extension-engineering.md, pi-grounding.md, and extension-research.md only for the implicated design questions.
- Prompt template, theme, package, settings, SDK/RPC/JSON integration, or standalone CLI: use surface selection, then read the current installed Pi document for the selected surface. Use extensions.md when extension code or an extension boundary participates.
- Managed extension removal after the disposition is settled: read removal.md.
- Session or harness evidence audit: use the Audit skill at repository-root path
skills/audit/SKILL.mdas the entrypoint. It owns intent resolution, bounded collection, unit separation, reconciliation, and audit reporting. - Extension-specific audit collection: from the Audit skill, read repository-root path
skills/audit/references/extension-telemetry.mdfor source contracts and windowed collection. - Extension utility, retention, removal, or incident disposition: from the Audit skill, read extension-audit.md after collection.
Complete when: every loaded reference serves a live decision or verification claim.
5. Implement at the selected boundary
Use the selected lane's procedure. Change only owned files. Keep temporary probes and evaluation artifacts outside tracked repository paths. Preserve supported public contracts and make lifecycle, cancellation, state, absence, failure, and delivery behavior explicit where they apply.
Choose local work or collaboration according to the task's dependencies and uncertainty. Use collaborative-work.md for work across workers or sessions. Assign integration and acceptance explicitly when work is split; a fixed worker topology is not a prerequisite for delivery.
Complete when: one reviewable capability reaches the requested outcome without unrelated governance layers or compatibility machinery.
6. Verify by claim
Read verification.md before completion. Select investigation, permanent protection, final acceptance and deliberate sampling by the evidence or protection they supply against total lifecycle cost. Use existing context and tool results; create a concise summary only when complex claims, disputes or handoffs need one. No default claim ledger is required.
Check evidence reach and continuing applicability before reuse. Recheck invalidated evidence and uncovered interactions, not every prior command. Skill activation, output quality, discovery and live UI are distinct claims. Follow the repository's single completion policy and final-verification owner; do not replace the layer that owns the claim with many cheap checks.
Complete when: accepted claims have sufficient applicable evidence. A preliminary or blocked report names the remaining necessary evidence and does not declare final acceptance.
7. Apply authority once
Confirm execution stays within granted authority under Intent authority in the universal AGENTS.md. Apply the relevant approval rules to new surfaces, destructive state changes, publication, and credential use; check supplied grants before treating an act as unapproved.
Stop only the actions that depend on a disputed fact or on authority you were not granted. Name that exact boundary and complete the rest of the authorized work.
Complete when: execution neither exceeds granted authority nor transfers a settled decision back to the operator.
Closure
Lead with the resulting operator-visible state and its consequence. Name the selected surface and load-bearing files when they help the operator locate or review the result. Explain a change or relationship only when it helps the operator use, review, or decide about the result. Summarize the evidence that supports the conclusion; do not dump working notes or a check transcript.
Report any discovery that changes the operator's available choices: evidence against the request's premise, a cheaper or safer route, an unanticipated cost, or an authority the next step will need. Report a limitation only when it blocks the requested conclusion, materially reduces confidence in it, or requires operator action. State the affected conclusion, the impact, and the narrowest next check or action. Omit irrelevant unperformed layers and optional stronger checks that would not change the conclusion. A binding repository completion or release gate remains material until satisfied or explicitly waived. Follow the owning repository's state-report requirements; otherwise, report repository state when it changes how the operator must handle the result.
Keep durable documentation about the current system; keep task chronology, transcripts, evaluation output, and private provenance outside the package.
Retain what the work taught
Retain a lesson only in the layer that applies it on a later relevant task:
- a deterministic implementation fault: the code fix and proportionate regression protection;
- a reusable operating method: its owning skill or reference, replacing contradicted text instead of adding an opposite rule;
- a durable operator fact or preference: Memory, under its own rules;
- sourced concern-specific expertise: the standing agent's profile through
agent_profile; - temporary unresolved work: the current context or a handover.
Keep the source, applicability, and material uncertainty with the lesson. Do not store repository facts in operator Memory, turn every error into a lesson, or record an agent interpretation as operator authority. A written note is not learning: the lesson counts when a later relevant task applies it. When a source or condition changes, revalidate the lesson where it lives, and correct or supersede it there.
04 同仓库更多 Skills
troll
Use when the operator wants a claim pressed at full strength: "troll this", "troll that claim", "realign this", "challenge that claim", "test this point", "this smells off", "is the session degrading", "steelman my angle", "set the other session back on track", "forge a redirect", "press it directly in that session", "pass the troll along". Fires on an explicit angle or on a bare instinct that something is off, never on your own initiative. Do not use for reviewing the operator's own code, dispatching an in-session checker, neutral fact-checks against the codebase, relaying an authorization to another session, or any request for a neutral verdict.
prime
Get up to speed on a topic before the operator gives the task. Use for preparation-only requests such as "survey this area", "orient yourself", or "get up to speed, then wait". Return a short, cited current-state summary with source coverage, then wait. Do not use for a single lookup, a question already answered in the session, or a request to start implementation, diagnosis, review, or research for an answer.
github
Use only for read-only GitHub outcomes through gh: repository metadata, code search, exact files at a branch, tag, or commit, history and diffs, issues, pull requests, checks, and releases, with immutable evidence links. Never use for requests that change GitHub state — create, edit, delete, merge, review, rerun, follow, subscribe, star, unstar. Do not use for ordinary local Git work.
dig
Dig into a question until it is answered with evidence: deep research, multi-source investigation, and troubleshooting of failures whose cause is not yet known. Use when the operator wants a cited answer, a root cause, or an exact blocker, for example "dig into why this keeps failing", "find out what really happened", "research X thoroughly and tell me", "figure out why it behaves this way", or "compare these options with evidence". The agent frames the question, finds the sources that own the answer, investigates directly or with other agents as the question warrants, checks the evidence, and synthesizes. Do not use for preparation-only orientation (prime), audits of Pi session or harness activity (audit), a single lookup or a question already answered, code review, or ordinary implementation with a known cause.
delegate
Work with other agents and choose how: do the work directly, take selective help, collaborate with peers, or coordinate a team, and revise that choice as the work develops. Use when the operator asks a session to delegate, collaborate, orchestrate, coordinate, lead, or manage agents, to act as main driver over a team, to have agents with their own context do work, to set up threads for agents, or to keep its own context clean on long-horizon research, planning, or implementation; also when a session must brief agents, choose presets, keep result references, supervise check-ins, recover from quota walls, or reset or hand over agents. Read it before the first dispatch of such work: the agent tool descriptions omit assignments, threads, preset choice, supervision, and close-out. Do not use for one evidence question (dig), orientation only (prime), Pi session audits (audit), harness surface changes (harness), or a small task the session can finish directly.
audit
Audit local Pi session and harness activity from ordinary intent or an explicit `/skill:audit` request. Use for evidence-based checks of agent episodes, extensions, tool use, supervision, discovery decisions, failures, outcomes, and recurring omissions, including bare audits and hints such as “how has this extension been doing” or “how often does this happen?”. Do not use for code or security audits, exact session retrieval, application telemetry, supplied billing data, or repairs and publication.