Skip to content

AGENTS.md

Latest commit

 

History

History
144 lines (123 loc) · 7.06 KB

AGENTS.md

File metadata and controls

144 lines (123 loc) · 7.06 KB

Repository Guidelines

This repository hosts Claude Code plugins, skills, hooks, and supporting documentation. Use this file as a light contributor guide and defer to CLAUDE.md for authoritative project rules.

Project Structure & Module Organization

  • plugins/<plugin-name>/: primary plugin content (see plugin.json).
    • skills/<skill-name>/SKILL.md: skill definitions with YAML frontmatter.
    • agents/: subagent definitions.
    • hooks/: hook configuration and scripts.
  • .claude/: agent memory, operational rules, and workflow guidance.
  • .claude-plugin/: local marketplace and plugin manifests.
  • specs/: design specs, audits, and planning docs.
  • .github/workflows/: CI, including Markdown linting.

Build, Test, and Development Commands

  • For any Claude Code workflows (skills, plugins, hooks, agents), invoke plugins/claude-ecosystem/skills/docs-management and follow the official documentation it loads.
  • Markdown linting guidance lives in plugins/code-quality/skills/markdown-linting.
  • Examples live in README.md, but defer to skills for current usage.

Coding Style & Naming Conventions

  • Formatting follows .editorconfig (2 spaces by default, 4 spaces for Python/C#, PowerShell uses CRLF).
  • For Claude Code naming and metadata conventions, invoke plugins/claude-ecosystem/skills/docs-management.
  • Markdown linting rules are defined in .markdownlint-cli2.jsonc; use the markdown-linting skill for guidance rather than duplicating details here.

Testing Guidelines

  • For Claude Code testing guidance, invoke plugins/claude-ecosystem/skills/docs-management.
  • Python testing conventions are documented in plugins/code-quality/skills/python.
  • Plugin-specific tests live alongside their skills; follow the relevant SKILL.md instructions when present.
  • Use Python 3.13+ for spaCy-backed operations.

Commit & Pull Request Guidelines

  • Use the Git-related skills as the source of truth for commit conventions and PR requirements (see plugins/git/skills/, especially push and hooks).
  • Keep this file minimal to avoid duplicating guidance that already lives in skills.

Agent-Specific Instructions

  • Read CLAUDE.md in the repo root first; it is the single source of truth.
  • If instructions conflict, update or follow CLAUDE.md and keep this file minimal to avoid duplication.
  • For any SKILL.md, apply the same progressive disclosure rule: read all directly referenced files needed to understand and execute the skill, then follow references one hop at a time until execution details are complete.
  • Do not execute scripts until you have:
    • confirmed required CLI arguments from the script or skill docs,
    • checked whether a dev mode environment variable is required,
    • reconciled any missing steps or flags in the command doc vs the skill.
  • Link, don’t duplicate: consolidate guidance into one canonical location and reference it elsewhere.
  • When a skill is referenced by name or path, open its SKILL.md and follow the documented workflow and precedence rules.
  • If a user mentions a specific product or ecosystem (e.g., Codex CLI, Claude, Gemini, Cursor), first scan available skills with rg --files -g "SKILL.md" and select the most relevant SKILL.md before proceeding.
  • Before stating a skill is missing, list skills with rg --files -g "SKILL.md" and check for a matching path.
  • For platform or framework changes, consult official documentation via the appropriate skill (Claude Code: docs-management, Gemini: gemini-cli-docs, Codex CLI: codex-cli-docs).

Codex CLI Guidance (OpenAI)

  • Use plugins/openai-ecosystem/skills/codex-cli-docs for Codex CLI docs; keep this file lean and defer details to that skill.
  • Prompting: include clear code pointers (greppable identifiers, stack traces, snippets) and explicit verification steps; split large tasks; paste logs for debugging; specify tool constraints when needed.
  • Instruction discovery: Codex layers global and project AGENTS.md files with AGENTS.override.md taking precedence; fallback filenames and size limits are configured in ~/.codex/config.toml (project_doc_fallback_filenames, project_doc_max_bytes); CODEX_HOME changes the global scope.
  • Sandbox/approvals: network is off by default; approvals are required outside the workspace; prefer read-only in non-versioned folders and be cautious with full access or enabling web search.
  • Configuration: ~/.codex/config.toml is shared by CLI and IDE; use profiles, feature flags under [features], and .rules to pre-approve command prefixes when appropriate.
  • Windows: prefer WSL for stronger sandboxing; native Windows sandbox support is experimental.

Claude Code Startup Parity (Static Memory)

  • Always read CLAUDE.md first. It is the single source of truth for repo rules.
  • Immediately after, read every memory file referenced in CLAUDE.md (all "Always Loaded" and "Context-Dependent" entries, plus the topics index). Do not skip any; treat this as mandatory startup.
  • Keep this section minimal: CLAUDE.md is the canonical list of memory files.

Claude Code Plugin + Skill Shim (Cursor Parity)

  • Mirrors .cursor/rules/claude-code-plugins.mdc and .cursor/rules/claude-skills.mdc so Codex has the same plugin/skill context.
  • Plugin discovery order:
    • plugins/ (repo source of plugins)
    • ~/.claude/plugins/marketplaces/<marketplace>/<plugin>/ (installed plugins)
    • .claude/plugins/ (project-local plugins)
  • Marketplace catalogs:
    • .claude-plugin/marketplace.json (local marketplace)
    • ~/.claude/marketplace.json (global marketplace)
    • Use docs-management doc_id code-claude-com-docs-en-plugin-marketplaces for schema and field details.
  • Plugin components and defaults (canonical in doc_id code-claude-com-docs-en-plugins-reference):
    • Commands: commands/ (Markdown with frontmatter)
    • Agents: agents/ (Markdown with frontmatter)
    • Skills: skills/<skill-name>/SKILL.md (+ optional references/scripts)
    • Hooks: hooks/hooks.json (or inline in plugin.json)
    • MCP servers: .mcp.json (or inline in plugin.json)
  • plugin.json defines metadata and optional custom paths; ${CLAUDE_PLUGIN_ROOT} resolves the installed plugin root for hooks, MCP servers, and scripts.
  • Skill execution: follow the "Agent-Specific Instructions" section plus the referenced SKILL.md workflow and precedence rules.

Claude Code Component Inventory (Always Refresh)

  • Maintain a session inventory of Claude components from:
    • Repo .claude/ (agents, skills, hooks, output styles, MCP config).
    • Repo plugins/ (per-plugin skills, agents, hooks, MCP servers, output styles, and manifests).
    • User/global plugins under ~/.claude/plugins/marketplaces/ (Windows: %USERPROFILE%\.claude\plugins\marketplaces\), plus any project .claude/plugins/ entries.
  • Use rg --files for discovery. If sandbox blocks user-scope paths, request approval or ask the user to provide the list.
  • Use docs-management doc_ids code-claude-com-docs-en-plugins-reference and code-claude-com-docs-en-plugin-marketplaces for canonical schemas.