Agent Environment

English | Русский

Portable Agent Skills for durable code output and reliable state across long-running work.

Why

Agent quality depends on more than the immediate answer. Code comments become part of a maintenance interface, authorship metadata becomes part of repository history, and long-running work must survive tool loops, context limits, restarts, and handoffs without replaying an ever-growing transcript.

This repository packages two independent practices. Install either one or both.

Included skills

Skill	Use it for	Default scope
code-output-hygiene	Durable comments and human-only authorship metadata	Global
execution-state-hygiene	Compact operational state for long, resumable, or repetitive workflows	Project-local

code-output-hygiene keeps new comments focused on hidden constraints, invariants, edge cases, interoperability, safety, and necessary workarounds. It also prevents AI identity or generated-with branding from being added to Git commits, pull requests, merge requests, issues, releases, or changelogs.

execution-state-hygiene adapts the state-centric execution model described in SKILL.state: Scalable Long-Horizon Agent Skills. It separates immutable procedure, compact structured state, and the latest observation instead of replaying prior dialogue and tool history.

Choose a practice

Use code output hygiene whenever an agent writes or edits code, comments, commit messages, pull requests, or merge requests.

Use execution state hygiene when work:

• repeats across many tool calls;
• must resume after context compaction or a process restart;
• spans multiple isolated runs or handoffs;
• repeatedly carries the same large body of operational context.

Do not add structured-state overhead to a short task. Do not discard history when chronology is itself the subject, such as auditing, provenance debugging, or explaining past actions. A fixed schema is also a poor fit while the relevant state structure is still being discovered.

Compatibility

The skills use the portable SKILL.md format and can be discovered by compatible agent harnesses. The examples below cover Codex, Claude Code, Claude Desktop, and OpenCode. Other Agent-Skills-compatible tools can use the same skill directories.

The skills CLI provides shared discovery and installation. A harness may also support its own native project or user-level skill directory.

Install

Inspect available skills

npx skills add keonji/agent-environment --list

Install one skill in the current project

Project scope is the CLI default:

npx skills add keonji/agent-environment --skill code-output-hygiene

npx skills add keonji/agent-environment --skill execution-state-hygiene

Install both skills in the current project

npx skills add keonji/agent-environment --skill '*'

Install code output hygiene globally

npx skills add keonji/agent-environment --skill code-output-hygiene --global

Use global scope deliberately: every compatible project can discover a global skill. Execution state hygiene is normally project-local because its schema and activation boundary belong to a particular workflow.

Target CLI harnesses explicitly

npx skills add keonji/agent-environment --skill code-output-hygiene --agent codex claude-code opencode

Add --global when the targeted installation should be user-wide.

Install in Claude Desktop

Claude Desktop accepts one skill per uploaded ZIP. Clone or download this repository, then archive the individual skill directory—not the complete multi-skill repository:

git clone https://github.com/keonji/agent-environment.git
cd agent-environment/skills
zip -r code-output-hygiene.zip code-output-hygiene

Upload the archive from Customize → Skills → Add skill → Upload skill. The ZIP must contain the top-level code-output-hygiene/ directory with SKILL.md and its references/ directory inside it. Repeat with execution-state-hygiene/ only when that practice is appropriate for the Desktop workflow.

Install only for an OpenCode project

OpenCode discovers .opencode/skills/<name>/SKILL.md. To restrict execution state hygiene to OpenCode in one repository, copy only that skill into the native project directory:

git clone https://github.com/keonji/agent-environment.git /tmp/agent-environment
mkdir -p .opencode/skills
cp -R /tmp/agent-environment/skills/execution-state-hygiene .opencode/skills/

Review downloaded skills before use. Skills execute with the permissions of the hosting agent.

Use

Code output hygiene

Compatible harnesses can select the skill automatically when code, comments, or repository metadata are being written. It can also be invoked explicitly:

Apply code-output-hygiene while implementing this change and preparing its
commit metadata.

The policy affects new output. It does not request blanket removal of comments and does not proactively rewrite unrelated legacy comments.

Execution state hygiene

Activate the skill explicitly in a long-running worker or orchestration prompt:

Apply execution-state-hygiene to this resumable workflow. Treat STATE.yaml as
the compact operational state, reconcile it with authoritative tool results,
update only changed fields, and keep the chronological event log outside the
prompt.

Define the domain schema before the loop begins. The included state-schema.md provides a software and automation profile; adapt its fields when another domain requires different sufficient state.

Repository layout

agent-environment/
├── README.md
├── README.ru.md
├── LICENSE
└── skills/
    ├── code-output-hygiene/
    │   ├── SKILL.md
    │   └── references/evals.md
    └── execution-state-hygiene/
        ├── SKILL.md
        └── references/
            ├── state-schema.md
            ├── runtime-integration.md
            └── evals.md

Each skill owns its supporting references, so it can be installed independently.

State lifecycle

At step t, a state-centric runtime constructs the model input from:

At = (P, Σt, Ot)

• P: immutable procedure and constraints;
• Σt: current structured execution state;
• Ot: latest bounded environment observation.

The model proposes a state patch and next action. Deterministic runtime code validates the patch, merges it into a copy of state, validates the resulting state and action, persists atomically, and only then executes the action. The next observed result becomes Ot+1.

The paper describes a dictionary merge with null deletion semantics:

{
  "state_patch": {
    "phase": "verify",
    "obsolete_key": null
  },
  "action": "run_acceptance_suite"
}

Previous actions, observations, tool output, dialogue, and reasoning are not replayed. Full operational events can remain in an append-only external log for audit and recovery. The prompt stays bounded only when P, Σ, and O remain bounded.

Integration levels

Level	What it provides	What it cannot guarantee
Instruction-only checkpoint	Better resumability and more consistent handoffs	Patch validity, immutability, atomicity, rollback, or action safety
Runtime-enforced state	Deterministic validation, merge, persistence, permissions, and rollback	A sufficient schema or conflict-free concurrent writing by itself

The portable skill can guide either level. Installing it alone does not reproduce the paper's runtime architecture. Full guarantees require orchestration code as described in runtime-integration.md.

Never request or persist chain-of-thought. The persistent interface contains only the state patch, action, evidence references, and operational facts needed for later execution.

Verification

List installed skills:

npx skills list --json

List user-wide skills:

npx skills list --global --json

After installation, verify that each installed SKILL.md retains its referenced files. Behavioral acceptance cases are available in each skill's references/evals.md.

For a state runtime, also test:

• invalid and oversized patches are rejected without changing state;
• immutable fields cannot be changed;
• stale revisions and concurrent conflicts are rejected;
• authoritative observations override contradicted state;
• action validation is separate from patch validation;
• prompt size does not grow with elapsed steps.

Limitations

Structured execution state assumes that its schema captures every past fact relevant to the future. Information can be lost when future relevance was not recognized, when the schema must evolve during exploration, or when history is the desired output.

The referenced paper evaluates single-agent execution. Concurrent writers need deterministic conflict resolution beyond that evaluated method. Smaller models may also produce whole-state overwrites, type errors, or malformed JSON; use patch-only output, deterministic validation, and constrained decoding where available.

Benefits depend on task horizon, model behavior, and runtime overhead. An independent adaptation record reports that short runs can show parity or additional state-contract cost and keeps the feature disabled by default. Measure on the intended workload before making it universal.

Safety and authorship

• Skills do not grant additional permissions. The hosting harness remains responsible for approvals, sandboxing, and tool policy.
• Validate actions separately from state patches before external side effects.
• Keep secrets and large tool output outside prompt-facing state.
• Preserve legitimate human and organization attribution.
• Do not add AI identity or generated-with branding to repository history or collaboration artifacts.

References

• SKILL.state: Scalable Long-Horizon Agent Skills — research basis for state-centric execution.
• Agent Skills CLI — portable discovery and installation.
• agents-best-practices — an independent, broader collection of agent-harness design practices maintained in its own repository; it is referenced, not bundled here.
• Apex Router adaptation record — independent implementation and measured rollout notes.

License

MIT — see LICENSE.