contextos-agents

Maintain your coding-agent rules in one place.
Export them to supported tools and catch outdated configs in CI.

Quickstart · Установка на русском · Supported agents · Guide · Contributing

---

Using several coding agents in the same project? A rule updated for one tool can leave another tool's configuration behind. ContextOS keeps your rules in version-controlled Markdown, exports them to supported agent formats, and checks whether those exports still match their sources.

It is useful when you or your team maintain instructions across multiple tools or need a configuration check before merging changes. If a small, stable instruction file already covers your workflow, you may not need an extra tool; see alternatives for an honest comparison.

_{Change a rule. Catch stale exports. Bring them back in sync.}

Quickstart

Install core 3.0.0 with every bundled and catalog skill, then use the same project in Antigravity, Codex and Claude Code. ContextOS installs the rules; install and sign in to your coding client separately. No model API key or MCP server is required by ContextOS.

Requires Node.js 22+ and npm. Open a terminal in the root of the project you want the agents to work on, not in the ContextOS repository. For a detailed walkthrough, see установка на русском.

1. Install and export all skills.

Install the exact stable version from npm:

npm install --save-dev --save-exact contextos-agents@3.0.0
npx --no-install contextos init --all
npx --no-install contextos compile
npx --no-install contextos export gemini,claude
npx --no-install contextos export gemini,claude --check --json

Expect "status": "pass", "hasDrift": false and exit code 0. Open this same project folder in your client and start a fresh chat to check discovery. init --all installs the seven core skills and every skill in this version's catalog. Skill bodies are selected as needed by the client; installing them all does not mean every body is inserted into every prompt.

In PowerShell, use npm.cmd and npx.cmd if execution policy blocks the .ps1 wrappers. These instructions work for projects in any language, including a project without an existing package.json.

2. Choose your clients.

The combined export above covers all three. These are alternative export targets:

Client	Export command	Where the client finds skills
Antigravity	npx --no-install contextos export gemini	.agents/skills/*/SKILL.md; activation rules in .agents/rules/
Codex CLI / Desktop	npx --no-install contextos export gemini	.agents/skills/*/SKILL.md
Claude Code	npx --no-install contextos export claude	.claude/skills/*/SKILL.md and .claude/rules/*.md
All supported clients	npx --no-install contextos export all	Also exports Cursor, Copilot, Aider and Zed

gemini is the adapter name shared by Antigravity and Codex. There is no export codex or export antigravity command. init --all installs all skills; export all selects all client formats. Check the same target you exported, for example npx --no-install contextos export all --check --json.

For an existing ContextOS project, add the remaining catalog skills with npx --no-install contextos skill add --all, then compile and export again. This adds catalog skills, not the seven core skills, and retains your active profile. A profile can exclude installed skills. See initialization options for smaller installs and updating an existing setup.

If you prefer the Git source tag, install Git and use this alternative for the first command; initialization and exports stay the same:

npm install --save-dev --save-exact --ignore-scripts "git+https://github.com/kok-o/contextos-agents.git#v3.0.0"

The reviewed archive is another installation option. See the 3.0.0 release for the accepted bytes and validation record.

Add your own team rule

init prepares .agents/project/skills/ for your own rules. For a smaller fresh setup, use init --with-core for just the seven core skills, or plain init for an empty rule folder. Run one initialization option per project.

Save this as .agents/project/skills/team-auth/SKILL.md:

---
name: team-auth
description: "Team rules for authentication code."
activation: always
---
# Team security

- Never log authorization headers.

activation decides how the rule reaches each agent: always (part of every session), globs (only for matching files, with a globs: list) or auto (the agent decides from the description; the default).

Optional manifests use skill.v2.yaml before skill.yaml and can declare an entrypoint and resources. Their activation fields override entrypoint frontmatter; see the source and activation contract.

Compile, export, and check after adding or editing a rule:

npx --no-install contextos compile
npx --no-install contextos export all
npx --no-install contextos export all --check --json

The check should report "status": "pass", "hasDrift": false, and exit code 0. The rule is now in the files each agent reads, for example .claude/rules/team-auth.md, .cursor/rules/team-auth.mdc and .agents/skills/team-auth/SKILL.md.

See drift detection: add - Never log session tokens. to the same source file, then run:

npx --no-install contextos export all --check --json

The check reports "status": "drift" and exits with code 1: the exports are out of date. Run npx --no-install contextos export all and check again to return to pass. Commit the source rules, generated files and lockfile together.

Edit your rules under .agents/project/skills/; generated files are managed outputs. To use a single adapter, replace all with its name, for example cursor. Files you already have, such as CLAUDE.md or a Copilot instruction file, keep your text; ContextOS refuses to overwrite a file it did not write (--force replaces it explicitly). See the step-by-step onboarding guide.

How a rule reaches each agent

Client	always	globs	auto
Claude Code	.claude/rules/<name>.md (loaded at launch)	.claude/rules/<name>.md with paths:	.claude/skills/<name>/SKILL.md
Cursor	.cursor/rules/<name>.mdc, alwaysApply: true	same file, globs:	same file, agent-requested
GitHub Copilot	body inside .github/copilot-instructions.md	routing table with source path	routing table with source path
Aider	body inside CONVENTIONS.md	skill index with /read hint	skill index with /read hint
Codex, Gemini CLI	.agents/skills/<name>/SKILL.md (a skill the client selects from its description)	same	same
Zed	.zed/rules.md and .zed/prompts/<name>.md (manual import)	same	same

Working in a team

Generated files are committed so that CI can check them. Two branches that edit different rules merge cleanly; if they add neighbouring rules, git may report a conflict in an aggregate file such as CONVENTIONS.md or in .agents/lockfile.v2.json. Rule sources never conflict this way. Resolve any source conflict, then run one command, which rebuilds every generated file from the sources, including files that still hold conflict markers:

npx --no-install contextos export all

Details, including CRLF checkouts and what to commit, are in the team workflow.

Check rule changes in CI

After committing a fresh export, run the same consistency check on pull requests. It checks agent configuration; your application's tests and security checks remain separate.

GitHub Actions example

Save as .github/workflows/contextos.yml. The action and CLI version are both pinned to the stable 3.0.0 release:

name: Agent rule consistency
on: [pull_request, push]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: kok-o/contextos-agents/.github/actions/contextos-gate@v3.0.0
        with:
          version: '3.0.0'
          adapters: 'all'
          working-directory: '.'

Set adapters to the adapter or adapters you actually exported. See CI configuration for version pinning.

Supported agents

Agent	What ContextOS writes
Claude Code	.claude/rules/*.md and .claude/skills/*/SKILL.md; your CLAUDE.md is not touched.
Cursor	Modular .cursor/rules/*.mdc files.
GitHub Copilot	A managed block in .github/copilot-instructions.md; text outside it is yours.
Codex, Gemini CLI	Shared native skills in .agents/skills/*/SKILL.md.
Aider	CONVENTIONS.md referenced by .aider.conf.yml.
Zed	Templates for manual import.

Export tests and live client loading are separate checks, and so is whether a model follows what it loaded. The compatibility matrix records which of the three was verified for each client, with versions and limitations.

Beyond the first rule

• Reuse skills: install catalog skills and stack presets, or keep team overrides. See skill management.
• Inspect task relevance: resolve recommends skills for a task and explains the selection, including your own rules (matched on name and description). It does not install or activate them. Ordinary exports use the installed skills allowed by the profile, independently of a task's selection. See resolution.
• Inspect staged changes: the separate scan command and optional hooks check supported secret, placeholder, and write-scope patterns. They report only, unless run with --enforce. See scanning and hooks.
• Upgrade from 2.x: run npx --no-install contextos update; see upgrading.

Scope and evidence

The core CLI manages rule sources, selection, exports and configuration checks. The optional MCP package is separate and maintained only for security and compatibility (npm install --save-dev contextos-mcp); agent execution and runtime orchestration remain experimental and are not expanded. Resuming MCP development requires a separate decision and a confirmed user scenario. Core has independent stable and RC release paths. Migration of the separate MCP package to its own maintenance workflow remains separate work.

Consistent configuration does not guarantee that a model follows every rule. The recorded calibration found no quality advantage over vanilla on its test corpus. ContextOS is not a sandbox and does not restrict what an agent does; see the security model. Install third-party skills only from sources you trust: their instructions are not sandboxed.

Documentation

I want to…	Read
Look up commands, presets, profiles, and diagnostics	Guide and cheat sheet
Try a task with a custom team rule	Onboarding
Work with branches, merges and CI	Team workflow
Check agent-specific behavior	Compatibility matrix
Compare with other ways to do this	Alternatives
Understand the guarantees and limits	Security model
Understand the compiler and support boundaries	Architecture · Product boundaries
Upgrade or recover a previous configuration	Migration and rollback
Review release evidence	Changelog · archived release records

Contributing

Bug reports, documentation fixes, and examples from real projects are welcome. See CONTRIBUTING.md or open an issue.

License

Apache-2.0. See NOTICE for attribution.