AGENTS.md · diff
git:20260326.caac78e to git:20260718.462ca93
44 added, 0 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 scripts (preferred)
{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` (e.g., `deploy.sh`, `fetch-logs.sh`)
- **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
- Use `#!/bin/bash` shebang
- Use `set -e` for fail-fast behavior
- Write status messages to stderr: `echo "Message" >&2`
- Write machine-readable output (JSON) to stdout
- Include a cleanup trap for temp files
- Reference the script path as `/mnt/skills/user/{skill-name}/scripts/{script}.sh`
### 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:start -->
+ # 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` |
+
+ <!-- gitnexus:end -->
+