| name | project-conventions |
| description | Capture or refresh persisted project conventions. Use when the user wants to initialize AGENTS.md, project style, validation commands, or tool preferences so agents stop rediscovering rules each session. |
Project Conventions
Use this skill to turn repeated project discovery into durable guidance that
future agents can read directly.
When to Use This Skill
- The user asks to initialize, capture, refresh, or persist project rules.
- The user says agents keep rediscovering project style or validation commands.
- The user wants an
AGENTS.md, conventions file, or project profile.
- The user wants common validation commands and tool preferences for a project.
Do not use this skill for ordinary implementation work, one-off lint failures,
or broad codebase exploration unless the goal is to write durable project
guidance.
Preferred Output Location
Use the narrowest durable file that future agents will actually read:
- Existing project
AGENTS.md, if present.
- New project
AGENTS.md, for compact repo-wide rules.
- A referenced file such as
docs/conventions.md when the content is too long
for AGENTS.md.
Keep global user preferences in global agent instructions, not in a project
file. Keep project-specific conventions in the project.
Workflow
- Inspect existing durable guidance before searching elsewhere:
AGENTS.md, CLAUDE.md, README, CONTRIBUTING, .opencode/,
formatter/linter config, package metadata, lockfiles, CI, Makefile,
justfile, Taskfile, and language-specific config.
- Separate observed facts from inferred conventions.
- Capture only stable, reusable rules:
- project purpose and non-goals
- source layout and generated-file boundaries
- dependency manager and toolchain preferences
- formatting, linting, type-checking, testing, and documentation commands
- common validation commands for JS/TS, Python, Rust, Markdown, JSONC, and
spelling when applicable
- project-local validation commands agents should prefer for checks, tests,
builds, documentation, and spelling
- commit message style and review expectations
- Prefer project-native commands over ephemeral runners. Use ephemeral runners
only when the project has no pinned tool:
- JS/TS CLI tools:
bunx <tool>
- Python CLI tools:
uvx <tool>
- Other tools: use an existing command on
PATH or ask before introducing a
new installer or package-manager path.
- Ask before writing when a rule is inferred, opinionated, or would change the
user's workflow.
- After writing, tell the orchestrator to reuse the persisted guidance and use
focused local inspection only when the persisted guidance is missing, stale,
conflicting, or insufficient.
Validation Commands
This skill records which validation commands are correct for the project. It
does not treat project-local permission as a security boundary. Global opencode
permission controls the user's baseline trust policy; project guidance should
explain what to run, not silently expand what may run.
For unfamiliar or third-party repositories, document commands but do not infer
that they are safe. If the user wants different permission behavior, surface it
as an explicit configuration choice rather than burying it in project
conventions.
Common commands to record
Use the package manager and commands that the project actually uses.
- JS/TS:
bun test*, bun run test*, bun run lint*,
bun run typecheck*, bun run build*, or the equivalent npm/pnpm/yarn
scripts when those are the project standard.
- Python:
uv run pytest*, uvx pytest*, pytest*, uv run ruff check*,
uv run mypy*, uv run pyright*.
- Rust:
cargo test*, cargo +nightly test*, cargo check*,
cargo +nightly check*, cargo clippy*, cargo +nightly clippy*,
cargo doc*, cargo +nightly doc*.
- Documentation and spelling: project-native docs build commands and
typos*
when accepted by the project.
Commands to label with risk
- Long-running, networked, deployment, migration, publish, install, or external
service commands.
- Destructive filesystem commands.
- VCS history destruction or force push.
- In-place fix modes unless the user explicitly asks:
--fix, --write,
--write-changes, -w, cargo clippy --fix*.
JSONC Validation
Prefer a tool that matches the real consumer.
- For opencode config, prefer
opencode debug config* because it exercises the
actual loader.
- Do not use
python -m json.tool for JSONC; it rejects comments and trailing
commas.
- If only syntax checking is needed, use a JSONC-aware parser or a formatter
that explicitly supports JSONC.
Output Template
When drafting persisted guidance, keep it compact:
# Project Agent Instructions
## Project Context
- ...
## Layout and Boundaries
- ...
## Tooling and Validation
- Format: ...
- Lint: ...
- Type check: ...
- Test: ...
- Docs: ...
## Command Risk
- Preferred validation commands: ...
- Risky or long-running commands: ...
- Commands not to run without explicit user intent: ...
## Style and Review
- ...
