Initial commit

2025-11-30 08:43:13 +08:00
commit f6d4a68978
178 changed files with 51030 additions and 0 deletions
--- a/skills/agents/SKILL.md
+++ b/skills/agents/SKILL.md
@@ -0,0 +1,390 @@
+---
+name: agents
+version: 1.1.0
+description: Generate and maintain AGENTS.md files following the public agents.md convention. Use when creating documentation for AI agent workflows, onboarding guides, or when standardizing agent interaction patterns across projects.
+license: Complete terms in LICENSE.txt
+---
+
+# AGENTS.md Generator Skill
+
+Generate and maintain AGENTS.md files following the public agents.md convention.
+
+## What This Skill Does
+
+Creates hierarchical AGENTS.md documentation for software projects:
+
+- **Thin root files** (~30 lines) with precedence rules and global defaults
+- **Scoped files** for subsystems (backend/, frontend/, internal/, cmd/, etc.)
+- **Auto-extracted commands** from Makefile, package.json, composer.json, go.mod
+- **Managed headers** marking files as agent-maintained with timestamps
+- **Language-specific templates** for Go, PHP, TypeScript, Python, and hybrid projects
+- **Idempotent updates** that preserve existing structure
+
+Based on analysis of 21 real AGENTS.md files across Netresearch projects.
+
+## When to Use This Skill
+
+- **New projects**: Establish baseline AGENTS.md structure
+- **Existing projects**: Standardize agent documentation
+- **Team onboarding**: Provide AI assistants with project context
+- **Multi-repo consistency**: Apply same standards across repositories
+- **Documentation updates**: Refresh after major changes
+
+## Usage
+
+### Generate for Current Project
+
+```bash
+# Basic generation (thin root + auto-detected scopes)
+/tmp/agents-skill/scripts/generate-agents.sh .
+
+# Dry-run to preview what will be created
+/tmp/agents-skill/scripts/generate-agents.sh . --dry-run
+
+# Verbose output with detection details
+/tmp/agents-skill/scripts/generate-agents.sh . --verbose
+```
+
+### Template Styles
+
+```bash
+# Thin root (default, ~30 lines, simple-ldap-go style)
+/tmp/agents-skill/scripts/generate-agents.sh . --style=thin
+
+# Verbose root (~100-200 lines, ldap-selfservice style)
+/tmp/agents-skill/scripts/generate-agents.sh . --style=verbose
+```
+
+### Update Existing Files
+
+```bash
+# Update timestamps and refresh auto-extracted content
+/tmp/agents-skill/scripts/generate-agents.sh . --update
+
+# Force regeneration (overwrites existing, keeps structure)
+/tmp/agents-skill/scripts/generate-agents.sh . --force
+```
+
+### Validation
+
+```bash
+# Validate existing AGENTS.md structure
+/tmp/agents-skill/scripts/validate-structure.sh .
+
+# Check for missing scoped files
+/tmp/agents-skill/scripts/detect-scopes.sh .
+```
+
+## Supported Project Types
+
+### Languages & Frameworks
+
+- **Go**: Libraries, web apps (Fiber/Echo/Gin), CLI tools (Cobra/urfave/cli)
+- **PHP**: Composer packages, TYPO3 extensions, Laravel/Symfony apps
+- **TypeScript/JavaScript**: React, Next.js, Vue, Node.js, Express
+- **Python**: pip, poetry, pipenv, Django, Flask, FastAPI
+- **Hybrid**: Multi-language projects (auto-creates scoped files per stack)
+
+### Detection Signals
+
+| Signal | Detection |
+|--------|-----------|
+| `go.mod` | Go project, extracts version |
+| `composer.json` | PHP project, detects TYPO3/Laravel |
+| `package.json` | Node.js project, detects framework |
+| `pyproject.toml` | Python project, detects poetry/ruff |
+| `Makefile` | Extracts targets with `##` comments |
+| `.github/workflows/` | Extracts CI checks |
+| `docker-compose.yml` | Docker-first setup |
+
+## Output Structure
+
+### Thin Root (Default)
+
+**~30 lines** following `simple-ldap-go` pattern:
+
+```markdown
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: YYYY-MM-DD -->
+
+# AGENTS.md (root)
+
+**Precedence:** The **closest AGENTS.md** to changed files wins. Root holds global defaults only.
+
+## Global rules
+- Keep PRs small (~≤300 net LOC)
+- Conventional Commits: type(scope): subject
+- Ask before: heavy deps, full e2e, repo rewrites
+- Never commit secrets or PII
+
+## Minimal pre-commit checks
+- Typecheck: [auto-detected from build tools]
+- Lint: [auto-detected from linters]
+- Format: [auto-detected from formatters]
+- Tests: [auto-detected from test runners]
+
+## Index of scoped AGENTS.md
+- `./backend/AGENTS.md` — Backend services
+- `./frontend/AGENTS.md` — Frontend application
+
+## When instructions conflict
+Nearest AGENTS.md wins. User prompts override files.
+```
+
+### Scoped Files (9-Section Schema)
+
+Each scoped file follows this structure:
+
+1. **Overview**: Purpose of this subsystem
+2. **Setup & environment**: Prerequisites, installation
+3. **Build & tests**: File-scoped commands (preferred)
+4. **Code style & conventions**: Language-specific standards
+5. **Security & safety**: Security practices
+6. **PR/commit checklist**: Pre-commit requirements
+7. **Good vs. bad examples**: Concrete code samples
+8. **When stuck**: Where to find help
+9. **House Rules** (optional): Overrides of global rules
+
+### Managed Header
+
+All generated files include:
+
+```html
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-18 -->
+```
+
+This marks files as agent-maintained and provides update tracking.
+
+## Auto-Detection Features
+
+### Project Type Detection
+
+```bash
+$ /tmp/agents-skill/scripts/detect-project.sh .
+{
+  "type": "go-web-app",
+  "language": "go",
+  "version": "1.24",
+  "build_tool": "make",
+  "has_docker": true,
+  "quality_tools": ["golangci-lint", "gofmt"],
+  "test_framework": "testing",
+  "ci": "github-actions"
+}
+```
+
+### Scope Detection
+
+Automatically creates scoped AGENTS.md for directories with ≥5 source files:
+
+```bash
+$ /tmp/agents-skill/scripts/detect-scopes.sh .
+{
+  "scopes": [
+    {"path": "internal", "type": "backend-go", "files": 15},
+    {"path": "cmd", "type": "cli", "files": 3},
+    {"path": "examples", "type": "examples", "files": 8}
+  ]
+}
+```
+
+### Command Extraction
+
+Extracts actual commands from build tools:
+
+```bash
+$ /tmp/agents-skill/scripts/extract-commands.sh .
+{
+  "typecheck": "go build -v ./...",
+  "lint": "golangci-lint run ./...",
+  "format": "gofmt -w .",
+  "test": "go test -v -race -short ./...",
+  "build": "go build -o bin/app ./cmd/app"
+}
+```
+
+## Examples
+
+Real-world examples from Netresearch projects in `references/examples/`:
+
+### Go Library (simple-ldap-go)
+
+**Perfect thin root** (26 lines):
+- Minimal global rules
+- File-scoped commands
+- Clear scope index
+- No duplication
+
+### Hybrid App (ldap-selfservice-password-changer)
+
+**Go backend + TypeScript frontend**:
+- Root with quick navigation
+- Scoped: `internal/AGENTS.md` (Go)
+- Scoped: `internal/web/AGENTS.md` (TypeScript + Tailwind)
+
+### PHP TYPO3 Extension (t3x-rte_ckeditor_image)
+
+**Composer-based with Make targets**:
+- Root with emoji headers
+- Scoped: `Classes/AGENTS.md` (PHP backend)
+- Scoped: `Documentation/AGENTS.md` (RST docs)
+- Scoped: `Tests/AGENTS.md` (PHPUnit tests)
+
+### Python CLI (coding_agent_cli_toolset)
+
+**Script-heavy toolset**:
+- Root with precedence focus
+- Scoped: `scripts/AGENTS.md`
+
+## Customization
+
+### Override Templates
+
+Copy templates to project and modify:
+
+```bash
+cp /tmp/agents-skill/templates/root-thin.md ./.agents-templates/root.md
+# Edit ./.agents-templates/root.md
+/tmp/agents-skill/scripts/generate-agents.sh . --template-dir=./.agents-templates
+```
+
+### Add Custom Sections
+
+Templates support placeholders:
+- `{{PROJECT_NAME}}` - From package.json/composer.json/go.mod
+- `{{PROJECT_TYPE}}` - Auto-detected type
+- `{{LANGUAGE}}` - Primary language
+- `{{BUILD_COMMANDS}}` - Extracted commands
+- `{{QUALITY_TOOLS}}` - Detected linters/formatters
+- `{{TIMESTAMP}}` - Current date (YYYY-MM-DD)
+
+## Idempotent Updates
+
+Safe to run multiple times:
+
+1. Checks existing files
+2. Preserves custom content in sections
+3. Updates only auto-extracted parts (commands, versions)
+4. Refreshes timestamps
+5. Adds missing sections
+6. No changes if nothing updated
+
+## Validation
+
+```bash
+# Check structure compliance
+/tmp/agents-skill/scripts/validate-structure.sh .
+
+# Validates:
+# ✅ Root is thin (≤50 lines or has index)
+# ✅ All scoped files have 9 sections
+# ✅ Managed headers present
+# ✅ Precedence statement in root
+# ✅ Links from root to scoped files work
+# ✅ No duplicate content between root and scoped
+```
+
+## Integration with Claude Code
+
+### As Marketplace Skill
+
+Add to `claude-code-marketplace`:
+
+```json
+{
+  "name": "agents",
+  "description": "Generate AGENTS.md files following public convention",
+  "version": "1.0.0",
+  "source": "./skills/agents"
+}
+```
+
+### Direct Usage
+
+```bash
+# Clone skill
+git clone https://github.com/netresearch/agents-skill.git /tmp/agents-skill
+
+# Generate for current project
+/tmp/agents-skill/scripts/generate-agents.sh .
+```
+
+## Structure Standards Application
+
+**When creating root AGENTS.md files**, keep them thin (~30 lines):
+- Include clear precedence statement at top
+- Define minimal global rules only (PR size, commit format, safety)
+- List pre-commit checks (typecheck, lint, format, test)
+- Provide scope index linking to scoped files
+- Move detailed setup to scoped files (not in root)
+- Move language-specific patterns to scoped files (not in root)
+- Move extensive examples to scoped files (not in root)
+
+**When determining scope boundaries**, create scoped files for:
+- Different technology stacks: `backend/`, `frontend/`, `api/`
+- Package visibility: `internal/`, `pkg/` (Go projects)
+- CLI tools: `cmd/`, `cli/`
+- Utility scripts: `scripts/`
+- Documentation and examples: `docs/`, `examples/`
+- Testing infrastructure: `tests/`, `testutil/`
+
+**When extracting commands**, automate extraction from:
+- Makefile targets with `##` comments
+- package.json scripts section
+- composer.json scripts section
+- CI workflow files (.github/workflows/, .gitlab-ci.yml)
+- Never manually duplicate commands that exist in build tools
+
+## Troubleshooting
+
+### No Commands Detected
+
+```bash
+# Check what was detected
+/tmp/agents-skill/scripts/extract-commands.sh . --verbose
+
+# Fallback: Specify commands manually
+/tmp/agents-skill/scripts/generate-agents.sh . --commands='{"lint":"make lint","test":"make test"}'
+```
+
+### Wrong Project Type
+
+```bash
+# Override auto-detection
+/tmp/agents-skill/scripts/generate-agents.sh . --type=go-library
+
+# Supported types:
+# go-library, go-web-app, go-cli
+# php-library, php-typo3, php-laravel
+# typescript-react, typescript-node
+# python-library, python-cli
+# hybrid
+```
+
+### Scoped File Not Created
+
+```bash
+# Check scope detection
+/tmp/agents-skill/scripts/detect-scopes.sh .
+
+# Manually specify scopes
+/tmp/agents-skill/scripts/generate-agents.sh . --scopes=internal,cmd,examples
+```
+
+## Contributing
+
+Improvements welcome! Common additions:
+- New language templates
+- Better command extraction
+- Additional validation rules
+- More real-world examples
+
+## License
+
+GPL-2.0-or-later (matching other Netresearch skills)
+
+## References
+
+- **Analysis**: `references/analysis.md` - Analysis of 21 real AGENTS.md files
+- **Prompt**: `references/prompt.md` - Original generation prompt/rule
+- **Examples**: `references/examples/` - Real-world AGENTS.md files
+- **Best Practices**: `references/best-practices.md` - Writing guide