git:20260816.5c2125d to git:20260905.20a4e97

0 added, 44 removed. Audit A to A.

# AGENTS.md

This file provides guidance to AI coding agents (Claude Code, Cursor, Copilot, etc.) when working with code in this repository.

use skill-creator skill for creating agent skill

## Repository Overview

A collection of skills for AI agents. Skills are packaged instructions and scripts that extend Claude's capabilities.

## Creating a New Skill

### Directory Structure

```

skills/

{skill-name}/ # kebab-case directory name

SKILL.md # Required: skill definition

scripts/ # Required: executable scripts

{script-name}.sh # Bash or Python, both first-class (.sh / .py)

{skill-name}.zip # Required: packaged for distribution

```

### Naming Conventions

- **Skill directory**: `kebab-case` (e.g., `system-prompt-creator`, `log-monitor`)

- **SKILL.md**: Always uppercase, always this exact filename

- **Scripts**: `kebab-case.sh` for Bash (e.g., `deploy.sh`, `fetch-logs.sh`); `snake_case.py` for new Python scripts (e.g., `profile_data.py`, `board_check.py`) — one older script, `export-deck-pdf.py`, predates this and stays kebab-case

- **Zip file**: Must match directory name exactly: `{skill-name}.zip`

### SKILL.md Format

```markdown

---

name: {skill-name}

description: {One sentence describing when to use this skill. Include trigger phrases like "Deploy my app", "Check logs", etc.}

---

# {Skill Title}

{Brief description of what the skill does.}

## How It Works

{Numbered list explaining the skill's workflow}

## Usage

```bash

bash /mnt/skills/user/{skill-name}/scripts/{script}.sh [args]

```

**Arguments:**

- `arg1` - Description (defaults to X)

**Examples:**

{Show 2-3 common usage patterns}

## Output

{Show example output users will see}

## Present Results to User

{Template for how Claude should format results when presenting to users}

## Troubleshooting

{Common issues and solutions, especially network/permissions errors}

```

### Best Practices for Context Efficiency

Skills are loaded on-demand — only the skill name and description are loaded at startup. The full `SKILL.md` loads into context only when the agent decides the skill is relevant. To minimize context usage:

- **Keep SKILL.md under 500 lines** — put detailed reference material in separate files

- **Write specific descriptions** — helps the agent know exactly when to activate the skill

- **Use progressive disclosure** — reference supporting files that get read only when needed

- **Prefer scripts over inline code** — script execution doesn't consume context (only output does)

- **File references work one level deep** — link directly from SKILL.md to supporting files

### Script Requirements

Bash and Python are both first-class — pick whichever fits the job, don't rank one over the other:

- **Bash** for scaffolding and orchestration: creating files/directories, calling other CLIs, idempotent setup that reports created-vs-skipped (e.g., `init-project.sh`).

- **Python** for analysis tools: parsing, statistics, structured checks whose consumer is an agent reading prose, not a pipeline (e.g., `profile_data.py`, `board_check.py`).

- Bash scripts use a `#!/bin/bash` shebang and `set -e` for fail-fast behavior. Python scripts use a `#!/usr/bin/env python3` shebang.

- Status on stderr and machine-readable JSON on stdout are required only for scripts whose output is meant to be consumed programmatically — not for a scaffolder reporting to a human or an analysis tool an agent reads as prose.

- A script that serves both audiences should offer a `--json` flag (the convention, e.g. `run_probe.py --json`) rather than choosing one output for everyone.

- Include a cleanup trap only in scripts that create temporary state (e.g. files under `/tmp`); a script that only writes its own permanent output doesn't need one.

- Reference the script path as `/mnt/skills/user/{skill-name}/scripts/{script}.sh` (or `.py` for Python scripts)

### Creating the Zip Package

After creating or updating a skill:

```bash

cd skills

zip -r {skill-name}.zip {skill-name}/

```

### End-User Installation

Document these two installation methods for users:

**Coding agent**

```bash

cp -r skills/{skill-name} ~/.agents/skills/

```

**Claude Code:**

```bash

cp -r skills/{skill-name} ~/.claude/skills/

```

**claude.ai:**

Add the skill to project knowledge or paste SKILL.md contents into the conversation.

If the skill requires network access, instruct users to add required domains at `claude.ai/settings/capabilities`.

-

- # GitNexus — Code Intelligence

- This project is indexed by GitNexus as **agent-skills** (2469 symbols, 2775 relationships, 3 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({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"})`.

- ## 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/agent-skills/context` | Codebase overview, check index freshness |

- | `gitnexus://repo/agent-skills/clusters` | All functional areas |

- | `gitnexus://repo/agent-skills/processes` | All execution flows |

- | `gitnexus://repo/agent-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` |

-