Skip to content

AGENTS.md

Latest commit

 

History

History
110 lines (79 loc) · 5.57 KB

AGENTS.md

File metadata and controls

110 lines (79 loc) · 5.57 KB
Raw
description graycode-skills — validation, registry, and contribution conventions.
globs *.md,*.py,*.toml,*.yaml,*.yml
alwaysApply false

graycode-skills Conventions

Community skill packages for Rho.

Development workflow

When starting any new work (feature, fix, refactor, chore), always create a feature branch from main first. Never commit directly to main. Use branch naming conventions like feat/<description>, fix/<description>, or chore/<description>. Open a PR, ensure CI is green, then merge.

Structure

categories/<category>/<skill-name>/
├── SKILL.md              # Required
├── templates/            # Optional
├── examples/             # Optional
└── scripts/              # Optional

Validation

# Validate a single skill (pass the skill directory, not SKILL.md)
python tools/validate_skill.py categories/python/mdc-fastapi

# Full-corpus zero-warning gate (what CI runs)
python tools/validate_skill.py --all --warning-budget tools/validation_warning_budget.json

# Build the registry (fails on duplicate names or schema violations)
python tools/update_registry.py

# Regenerate the Claude Code marketplace after adding/removing skills or categories
python tools/sync_marketplace.py

# Full test suite (CI requires >= 88% coverage)
python -m pytest tests/ --cov --cov-fail-under=88

# Lint (CI runs `ruff check`; `ruff format` is not enforced, so do not mass-reformat)
ruff check .

The schema the gate enforces lives in manifest-schema.toml [enforced]; see CONTRIBUTING.md. First-party skills in categories/graycode/ must also pass python tools/check_agentskills.py --strict categories/graycode.

Ecosystem Boundaries

  • Extends Rho through public skill and plugin surfaces only (rho skills install GrayCodeAI/graycode-skills <name>, which installs into Rho's state directory; see README)
  • Do not reference support engine internals (flux/client, flux/catalog, flux/credentials, rho/internal/*) — consume only flux/engine, flux/llm, flux/graph, flux/tools
  • Removed legacy paths (graycode-router, harrier, shrike, swift, kestrel, merlin, graycode-cli/internal/*) must not be referenced

For full graycode-eco extension guidelines, see rho/AGENTS.md.

Optional: GitNexus code intelligence

The block below is generated by gitnexus analyze and applies only when the GitNexus MCP server and a local .gitnexus/ index are available (the index is not committed; /.gitnexus/ is gitignored). Without GitNexus, skip it: its MUST/NEVER rules cannot be satisfied, and the Validation commands above are the required checks.

GitNexus — Code Intelligence

This project is indexed by GitNexus as graycode-skills (210621 symbols, 225507 relationships, 136 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.

Index stale? Run node .gitnexus/run.cjs analyze from the project root — it auto-selects an available runner. No .gitnexus/run.cjs yet? npx gitnexus analyze (npm 11 crash → npm i -g gitnexus; #1939).

Always Do

  • MUST run impact analysis before editing any symbol. Before modifying a function, class, or method, run impact({target: "symbolName", direction: "upstream"}) and report the blast radius (direct callers, affected processes, risk level) to the user.
  • MUST run detect_changes() before committing to verify your changes only affect expected symbols and execution flows. For regression review, compare against the default branch: detect_changes({scope: "compare", base_ref: "main"}).
  • MUST warn the user if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
  • When exploring unfamiliar code, use query({search_query: "concept"}) to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
  • When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use context({name: "symbolName"}).
  • For security review, explain({target: "fileOrSymbol"}) lists taint findings (source→sink flows; needs analyze --pdg).

Never Do

  • NEVER edit a function, class, or method without first running impact on it.
  • NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
  • NEVER rename symbols with find-and-replace — use rename which understands the call graph.
  • NEVER commit changes without running detect_changes() to check affected scope.

Resources

Resource Use for
gitnexus://repo/graycode-skills/context Codebase overview, check index freshness
gitnexus://repo/graycode-skills/clusters All functional areas
gitnexus://repo/graycode-skills/processes All execution flows
gitnexus://repo/graycode-skills/process/{name} Step-by-step execution trace

CLI

Task Read this skill file
Understand architecture / "How does X work?" .claude/skills/gitnexus/gitnexus-exploring/SKILL.md
Blast radius / "What breaks if I change X?" .claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md
Trace bugs / "Why is X failing?" .claude/skills/gitnexus/gitnexus-debugging/SKILL.md
Rename / extract / split / refactor .claude/skills/gitnexus/gitnexus-refactoring/SKILL.md
Tools, resources, schema reference .claude/skills/gitnexus/gitnexus-guide/SKILL.md
Index, status, clean, wiki CLI commands .claude/skills/gitnexus/gitnexus-cli/SKILL.md