@synapta/skills 0.1.1 → 0.2.0

package/skills/repo-bootstrap/assets/root-verbose.md

@@ -0,0 +1,149 @@
+<!-- FOR AI AGENTS - Human readability is a side effect, not a goal -->
+<!-- Managed by agent: keep sections and order; edit content, not structure -->
+<!-- Last updated: {{TIMESTAMP}} | Last verified: {{VERIFIED_TIMESTAMP}} -->
+
+# AGENTS.md
+
+**Precedence:** The **closest AGENTS.md** to changed files wins. Root holds global defaults only.
+
+## Project Overview
+<!-- AGENTS-GENERATED:START project-overview -->
+{{PROJECT_DESCRIPTION}}
+
+**Tech Stack**: {{LANGUAGE}} {{VERSION}}, {{BUILD_TOOL}}, {{FRAMEWORK}}
+**Type**: {{PROJECT_TYPE}}
+<!-- AGENTS-GENERATED:END project-overview -->
+
+## Response Style
+- Answer first, elaborate only if needed. No sycophantic openers ("Great question!", "Absolutely!").
+- Lead with the answer for yes/no or status questions. Skip preamble.
+- Match response length to task complexity.
+
+## Global Rules
+- Keep PRs small (~≤300 net LOC)
+- Conventional Commits: `type(scope): subject`
+- Atomic commits (one logical change per commit) — never squash unless explicitly asked
+{{LANGUAGE_CONVENTIONS}}
+
+## Boundaries
+
+### Always Do
+- Run pre-commit checks before committing
+- Add tests for new code paths
+- Use conventional commit format: `type(scope): subject`
+- Keep dependencies updated
+- Validate all user inputs
+- **Show test output as evidence before claiming work is complete** — never say "try again", "should work now", "tested", "verified", or "all green" without pasted command output in the same turn
+- Before any edit, verify `pwd` resolves inside the intended repo worktree — not `.bare/`, not `~/.claude/skills/…`, not `~/.claude/plugins/cache/…` (those are read-only caches that get clobbered on update)
+- For upstream dependency fixes: run **full** test suite, not just affected tests
+- Force-push only with `--force-with-lease`
+
+### Ask First
+- Adding new dependencies
+- Modifying CI/CD configuration
+- Changing public API signatures
+- Running full e2e test suites
+- Repo-wide refactoring or rewrites
+- Modifying security-sensitive code
+- Changing database schemas
+- Any operation that touches >3 repos — produce a dry-run plan first
+
+### Never Do
+- Commit secrets, credentials, API keys, or PII
+- Modify vendor/, node_modules/, or generated files
+- Push directly to main/master branch — open a PR
+- Merge a PR before all review threads are resolved
+- Squash commits during merge/rebase unless the user explicitly asked
+- Edit installed skill/plugin cache paths (`~/.claude/skills/`, `~/.claude/plugins/cache/`, `**/.bare/**`)
+- Reply to review comments with bare "Addressed" or "Fixed" — cite the resolving commit SHA
+- Delete migration files or schema changes
+- Disable security features or linting rules
+- Hardcode environment-specific values
+- Use `secrets: inherit` in reusable GitHub Actions workflows (pass secrets explicitly)
+{{LANGUAGE_SPECIFIC_NEVER}}
+
+<!-- AGENTS-GENERATED:START module-boundaries -->
+{{MODULE_BOUNDARIES}}
+<!-- AGENTS-GENERATED:END module-boundaries -->
+
+## Development Workflow
+1. Create feature branch: `git checkout -b feature/description`
+2. Make changes with tests
+3. Run pre-commit checks (see below)
+4. Commit with conventional format
+5. Push and create PR
+6. Address review feedback
+7. Merge when approved
+
+## Agent Work Loop
+1. **Before coding**: Read nearest `AGENTS.md` + check Golden Samples for the area you're touching
+2. **After each change**: Run the smallest relevant check (lint → typecheck → single test)
+3. **Before committing**: Run full test suite if changes affect >2 files or touch shared code
+4. **Before claiming done**: Run verification and **show output as evidence** — never say "try again", "should work now", "tested", or "verified" without pasted command output
+
+## Pre-commit Checks
+> Source: {{COMMAND_SOURCE}} — CI-sourced commands are most reliable
+
+<!-- AGENTS-GENERATED:START precommit-checks -->
+**Always run before committing:**
+- Typecheck: {{TYPECHECK_CMD}}
+- Lint: {{LINT_CMD}}
+- Format: {{FORMAT_CMD}}
+- Tests: {{TEST_CMD}}
+- Build: {{BUILD_CMD}}
+<!-- AGENTS-GENERATED:END precommit-checks -->
+
+## Code Quality Standards
+<!-- AGENTS-GENERATED:START quality-standards -->
+{{QUALITY_STANDARDS}}
+<!-- AGENTS-GENERATED:END quality-standards -->
+
+<!-- AGENTS-GENERATED:START ci-rules -->
+{{CI_RULES_SECTION}}
+<!-- AGENTS-GENERATED:END ci-rules -->
+
+## Security & Safety
+- Never commit secrets, credentials, or PII
+- Validate all user inputs
+- Use parameterized queries for database access
+- Keep dependencies updated
+{{SECURITY_SPECIFIC}}
+
+## Testing Requirements
+<!-- AGENTS-GENERATED:START testing -->
+- Write tests for new features
+- Maintain {{TEST_COVERAGE}}% minimum coverage
+- Run fast tests locally: {{TEST_FAST_CMD}}
+- Run full suite in CI: {{TEST_FULL_CMD}}
+<!-- AGENTS-GENERATED:END testing -->
+
+## Key Decisions
+<!-- AGENTS-GENERATED:START key-decisions -->
+{{KEY_DECISIONS}}
+<!-- AGENTS-GENERATED:END key-decisions -->
+
+## Scoped AGENTS.md (MUST read when working in these directories)
+<!-- AGENTS-GENERATED:START scope-index -->
+{{SCOPE_INDEX}}
+<!-- AGENTS-GENERATED:END scope-index -->
+
+> **Agents**: When you read or edit files in a listed directory, you **must** load its AGENTS.md first. It contains directory-specific conventions that override this root file.
+
+## When Instructions Conflict
+Nearest AGENTS.md wins. User prompts override files.
+{{LANGUAGE_SPECIFIC_CONFLICT_RESOLUTION}}
+
+## Code Examples
+
+### Good Pattern
+{{GOOD_EXAMPLE}}
+
+### Avoid
+{{BAD_EXAMPLE}}
+
+## Documentation
+<!-- AGENTS-GENERATED:START documentation -->
+- Architecture: {{ARCHITECTURE_DOC}}
+- API docs: {{API_DOC}}
+- Contributing: {{CONTRIBUTING_DOC}}
+<!-- AGENTS-GENERATED:END documentation -->

package/skills/repo-bootstrap/assets/scoped/backend-go.md

@@ -0,0 +1,107 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
+
+# AGENTS.md — {{SCOPE_NAME}}
+
+<!-- AGENTS-GENERATED:START overview -->
+## Overview
+{{SCOPE_DESCRIPTION}}
+<!-- AGENTS-GENERATED:END overview -->
+
+<!-- AGENTS-GENERATED:START filemap -->
+## Key Files
+{{SCOPE_FILE_MAP}}
+<!-- AGENTS-GENERATED:END filemap -->
+
+<!-- AGENTS-GENERATED:START golden-samples -->
+## Golden Samples (follow these patterns)
+{{SCOPE_GOLDEN_SAMPLES}}
+<!-- AGENTS-GENERATED:END golden-samples -->
+
+<!-- AGENTS-GENERATED:START setup -->
+## Setup & environment
+{{INSTALL_LINE}}
+{{GO_VERSION_LINE}}
+{{GO_TOOLS_LINE}}
+{{ENV_VARS_LINE}}
+<!-- AGENTS-GENERATED:END setup -->
+
+<!-- AGENTS-GENERATED:START commands -->
+## Build & tests
+{{VET_LINE}}
+{{FORMAT_LINE}}
+{{LINT_LINE}}
+{{GOVULNCHECK_LINE}}
+{{TEST_LINE}}
+{{TEST_RACE_LINE}}
+{{TEST_SINGLE_LINE}}
+{{FUZZ_LINE}}
+{{BUILD_LINE}}
+<!-- AGENTS-GENERATED:END commands -->
+
+<!-- AGENTS-GENERATED:START code-style -->
+## Code style & conventions
+- Follow Go 1.{{GO_MINOR_VERSION}} idioms
+- Use standard library over external deps when possible
+- Errors: wrap with `fmt.Errorf("context: %w", err)`, lowercase no punctuation
+- Naming: `camelCase` for private, `PascalCase` for exported; ID/URL/HTTP not Id/Url/Http
+- Struct tags: use canonical form (json, yaml, etc.)
+- Comments: complete sentences ending with period
+- Package docs: first sentence summarizes purpose
+- Prefer `any` over `interface{}`; use generics `[T any]` where appropriate
+- Run `go fix ./...` after Go version upgrades to apply modernizers
+<!-- AGENTS-GENERATED:END code-style -->
+
+<!-- AGENTS-GENERATED:START security -->
+## Security & safety
+- Validate all inputs from external sources
+- Use `context.Context` for cancellation and timeouts
+- Avoid goroutine leaks: always ensure termination paths
+- Sensitive data: never log or include in errors
+- SQL: use parameterized queries only
+- File paths: validate and sanitize user-provided paths
+<!-- AGENTS-GENERATED:END security -->
+
+<!-- AGENTS-GENERATED:START quality-gates -->
+## Quality gates
+Run these checks before completing any review:
+```bash
+golangci-lint run --timeout 5m    # Linting (golangci-lint v2)
+go vet ./...                       # Static analysis
+govulncheck ./...                  # Vulnerability scan
+go test -race ./...                # Race detection
+```
+<!-- AGENTS-GENERATED:END quality-gates -->
+
+<!-- AGENTS-GENERATED:START checklist -->
+## PR/commit checklist
+{{TEST_CHECKLIST_LINE}}
+{{LINT_CHECKLIST_LINE}}
+{{FORMAT_CHECKLIST_LINE}}
+- [ ] `govulncheck ./...` reports no vulnerabilities
+- [ ] No goroutine leaks (ensure termination paths)
+- [ ] Error messages are descriptive and wrapped with `%w`
+- [ ] Public APIs have godoc comments
+- [ ] `context.Context` passed and respected in all I/O paths
+<!-- AGENTS-GENERATED:END checklist -->
+
+<!-- AGENTS-GENERATED:START examples -->
+## Patterns to Follow
+> **Prefer looking at real code in this repo over generic examples.**
+> See **Golden Samples** section above for files that demonstrate correct patterns.
+
+Key patterns:
+- Context handling: always pass and respect `context.Context`
+- Interfaces: define where used, not where implemented
+<!-- AGENTS-GENERATED:END examples -->
+
+<!-- AGENTS-GENERATED:START help -->
+## When stuck
+- Check Go documentation: https://pkg.go.dev
+- Review existing patterns in this codebase
+- Check root AGENTS.md for project-wide conventions
+- Run `go doc <package>` for standard library help
+<!-- AGENTS-GENERATED:END help -->
+
+## House Rules (project-specific)
+<!-- This section is NOT auto-generated - add your project-specific rules here -->
+{{HOUSE_RULES}}

package/skills/repo-bootstrap/assets/scoped/backend-php.md

@@ -0,0 +1,94 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
+
+# AGENTS.md — {{SCOPE_NAME}}
+
+<!-- AGENTS-GENERATED:START overview -->
+## Overview
+{{SCOPE_DESCRIPTION}}
+<!-- AGENTS-GENERATED:END overview -->
+
+<!-- AGENTS-GENERATED:START filemap -->
+## Key Files
+{{SCOPE_FILE_MAP}}
+<!-- AGENTS-GENERATED:END filemap -->
+
+<!-- AGENTS-GENERATED:START golden-samples -->
+## Golden Samples (follow these patterns)
+{{SCOPE_GOLDEN_SAMPLES}}
+<!-- AGENTS-GENERATED:END golden-samples -->
+
+<!-- AGENTS-GENERATED:START setup -->
+## Setup & environment
+{{INSTALL_LINE}}
+{{PHP_VERSION_LINE}}
+{{FRAMEWORK_LINE}}
+{{PHP_EXTENSIONS_LINE}}
+{{ENV_VARS_LINE}}
+<!-- AGENTS-GENERATED:END setup -->
+
+<!-- AGENTS-GENERATED:START commands -->
+## Build & tests
+{{TYPECHECK_LINE}}
+{{FORMAT_LINE}}
+{{LINT_LINE}}
+{{TEST_LINE}}
+{{BUILD_LINE}}
+<!-- AGENTS-GENERATED:END commands -->
+
+<!-- AGENTS-GENERATED:START code-style -->
+## Code style & conventions
+- Follow PSR-12 coding standard
+- Use strict types: `declare(strict_types=1);`
+- Type hints: always use for parameters and return types
+- Naming: `camelCase` for methods, `PascalCase` for classes
+- Visibility: always declare (public, protected, private)
+- PHPDoc: required for public APIs, include `@param` and `@return`
+{{FRAMEWORK_CONVENTIONS}}
+<!-- AGENTS-GENERATED:END code-style -->
+
+<!-- AGENTS-GENERATED:START security -->
+## Security & safety
+- Validate and sanitize all user inputs
+- Use prepared statements for database queries
+- Escape output in templates
+- Never use dynamic code execution functions
+- Sensitive data: never log or expose in errors
+- CSRF protection: enable for all forms
+- XSS protection: escape all user-generated content
+<!-- AGENTS-GENERATED:END security -->
+
+<!-- AGENTS-GENERATED:START checklist -->
+## PR/commit checklist
+{{TEST_CHECKLIST_LINE}}
+{{TYPECHECK_CHECKLIST_LINE}}
+{{FORMAT_CHECKLIST_LINE}}
+- [ ] No deprecated functions used
+- [ ] Public methods have PHPDoc
+- [ ] Security: inputs validated, outputs escaped
+<!-- AGENTS-GENERATED:END checklist -->
+
+<!-- AGENTS-GENERATED:START examples -->
+## Patterns to Follow
+> **Prefer looking at real code in this repo over generic examples.**
+> See **Golden Samples** section above for files that demonstrate correct patterns.
+<!-- AGENTS-GENERATED:END examples -->
+
+<!-- AGENTS-GENERATED:START help -->
+## When stuck
+- Check PHP documentation: https://www.php.net
+{{FRAMEWORK_DOCS_LINE}}
+- Review existing patterns in this codebase
+- Check root AGENTS.md for project-wide conventions
+<!-- AGENTS-GENERATED:END help -->
+
+<!-- AGENTS-GENERATED:START skill-reference -->
+## Skill Reference
+> For PHP 8.x modernization, type safety, and PHPStan compliance:
+> **Invoke skill:** `php-modernization`
+>
+> For Symfony projects, use the dedicated `symfony.md` scoped template instead of this generic PHP template.
+<!-- AGENTS-GENERATED:END skill-reference -->
+
+## House Rules (project-specific)
+<!-- This section is NOT auto-generated - add your project-specific rules here -->
+{{HOUSE_RULES}}

package/skills/repo-bootstrap/assets/scoped/backend-python.md

@@ -0,0 +1,84 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
+
+# AGENTS.md — {{SCOPE_NAME}}
+
+<!-- AGENTS-GENERATED:START overview -->
+## Overview
+{{SCOPE_DESCRIPTION}}
+<!-- AGENTS-GENERATED:END overview -->
+
+<!-- AGENTS-GENERATED:START filemap -->
+## Key Files
+{{SCOPE_FILE_MAP}}
+<!-- AGENTS-GENERATED:END filemap -->
+
+<!-- AGENTS-GENERATED:START golden-samples -->
+## Golden Samples (follow these patterns)
+{{SCOPE_GOLDEN_SAMPLES}}
+<!-- AGENTS-GENERATED:END golden-samples -->
+
+<!-- AGENTS-GENERATED:START setup -->
+## Setup & environment
+{{INSTALL_LINE}}
+{{PYTHON_VERSION_LINE}}
+{{PACKAGE_MANAGER_LINE}}
+{{VENV_LINE}}
+{{ENV_VARS_LINE}}
+<!-- AGENTS-GENERATED:END setup -->
+
+<!-- AGENTS-GENERATED:START commands -->
+## Build & tests
+{{TYPECHECK_LINE}}
+{{FORMAT_LINE}}
+{{LINT_LINE}}
+{{TEST_LINE}}
+{{BUILD_LINE}}
+<!-- AGENTS-GENERATED:END commands -->
+
+<!-- AGENTS-GENERATED:START code-style -->
+## Code style & conventions
+- Follow PEP 8 style guide
+- Use type hints for all function signatures
+- Naming: `snake_case` for functions/variables, `PascalCase` for classes
+- Docstrings: Google style, required for public APIs
+- Imports: group by stdlib, third-party, local (use isort)
+- Modern Python: prefer `|` over `Union`, `list` over `List`
+{{FRAMEWORK_CONVENTIONS}}
+<!-- AGENTS-GENERATED:END code-style -->
+
+<!-- AGENTS-GENERATED:START security -->
+## Security & safety
+- Validate and sanitize all user inputs
+- Use parameterized queries for database access
+- Never use dynamic code execution with untrusted data
+- Sensitive data: never log or expose in errors
+- File paths: validate and use `pathlib` for path operations
+- Subprocess: use list args, avoid shell=True with user input
+<!-- AGENTS-GENERATED:END security -->
+
+<!-- AGENTS-GENERATED:START checklist -->
+## PR/commit checklist
+{{TEST_CHECKLIST_LINE}}
+{{TYPECHECK_CHECKLIST_LINE}}
+{{LINT_CHECKLIST_LINE}}
+{{FORMAT_CHECKLIST_LINE}}
+- [ ] Public functions have docstrings
+<!-- AGENTS-GENERATED:END checklist -->
+
+<!-- AGENTS-GENERATED:START examples -->
+## Patterns to Follow
+> **Prefer looking at real code in this repo over generic examples.**
+> See **Golden Samples** section above for files that demonstrate correct patterns.
+<!-- AGENTS-GENERATED:END examples -->
+
+<!-- AGENTS-GENERATED:START help -->
+## When stuck
+- Check Python documentation: https://docs.python.org
+- Review existing patterns in this codebase
+- Check root AGENTS.md for project-wide conventions
+- Use `python -m pydoc <module>` for stdlib help
+<!-- AGENTS-GENERATED:END help -->
+
+## House Rules (project-specific)
+<!-- This section is NOT auto-generated - add your project-specific rules here -->
+{{HOUSE_RULES}}

package/skills/repo-bootstrap/assets/scoped/backend-typescript.md

@@ -0,0 +1,89 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
+
+# AGENTS.md — {{SCOPE_NAME}}
+
+<!-- AGENTS-GENERATED:START overview -->
+## Overview
+{{SCOPE_DESCRIPTION}}
+<!-- AGENTS-GENERATED:END overview -->
+
+<!-- AGENTS-GENERATED:START filemap -->
+## Key Files
+{{SCOPE_FILE_MAP}}
+<!-- AGENTS-GENERATED:END filemap -->
+
+<!-- AGENTS-GENERATED:START golden-samples -->
+## Golden Samples (follow these patterns)
+{{SCOPE_GOLDEN_SAMPLES}}
+<!-- AGENTS-GENERATED:END golden-samples -->
+
+<!-- AGENTS-GENERATED:START setup -->
+## Setup & environment
+{{INSTALL_LINE}}
+{{NODE_VERSION_LINE}}
+{{PACKAGE_MANAGER_LINE}}
+{{RUNTIME_LINE}}
+{{ENV_VARS_LINE}}
+<!-- AGENTS-GENERATED:END setup -->
+
+<!-- AGENTS-GENERATED:START commands -->
+## Build & tests
+{{TYPECHECK_LINE}}
+{{FORMAT_LINE}}
+{{LINT_LINE}}
+{{TEST_LINE}}
+{{BUILD_LINE}}
+{{DEV_LINE}}
+<!-- AGENTS-GENERATED:END commands -->
+
+<!-- AGENTS-GENERATED:START code-style -->
+## Code style & conventions
+- Use TypeScript strict mode (`strict: true` in tsconfig)
+- No `any` without explicit justification comment
+- Prefer `interface` over `type` for object shapes
+- Naming: `camelCase` for functions/vars, `PascalCase` for classes/types
+- Async/await over raw Promises
+- Prefer `const` over `let`, never use `var`
+- Destructure objects and arrays when appropriate
+{{FRAMEWORK_CONVENTIONS}}
+<!-- AGENTS-GENERATED:END code-style -->
+
+<!-- AGENTS-GENERATED:START security -->
+## Security & safety
+- Validate all user inputs (use zod or similar)
+- Parameterized queries only (no string concatenation)
+- Never use dynamic code execution with user data
+- Sensitive data: never log or expose in errors
+- Environment: use dotenv, never hardcode secrets
+- CORS: configure explicitly, no wildcard in production
+- Rate limiting: implement for public endpoints
+<!-- AGENTS-GENERATED:END security -->
+
+<!-- AGENTS-GENERATED:START checklist -->
+## PR/commit checklist
+{{TEST_CHECKLIST_LINE}}
+{{TYPECHECK_CHECKLIST_LINE}}
+{{LINT_CHECKLIST_LINE}}
+{{FORMAT_CHECKLIST_LINE}}
+- [ ] No `any` types without justification
+- [ ] API endpoints have validation
+- [ ] Error responses don't leak internals
+<!-- AGENTS-GENERATED:END checklist -->
+
+<!-- AGENTS-GENERATED:START examples -->
+## Patterns to Follow
+> **Prefer looking at real code in this repo over generic examples.**
+> See **Golden Samples** section above for files that demonstrate correct patterns.
+<!-- AGENTS-GENERATED:END examples -->
+
+<!-- AGENTS-GENERATED:START help -->
+## When stuck
+- Check Node.js docs: https://nodejs.org/docs
+- TypeScript handbook: https://www.typescriptlang.org/docs
+- Review existing patterns in this codebase
+- Check root AGENTS.md for project-wide conventions
+<!-- AGENTS-GENERATED:END help -->
+
+## House Rules (project-specific)
+<!-- This section is NOT auto-generated - add your project-specific rules here -->
+{{HOUSE_RULES}}

package/skills/repo-bootstrap/assets/scoped/claude-code-skill.md

@@ -0,0 +1,101 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
+
+# AGENTS.md — {{SCOPE_NAME}}
+
+<!-- AGENTS-GENERATED:START overview -->
+## Overview
+{{SCOPE_DESCRIPTION}}
+<!-- AGENTS-GENERATED:END overview -->
+
+<!-- AGENTS-GENERATED:START filemap -->
+## Key Files
+{{SCOPE_FILE_MAP}}
+<!-- AGENTS-GENERATED:END filemap -->
+
+<!-- AGENTS-GENERATED:START golden-samples -->
+## Golden Samples (follow these patterns)
+{{SCOPE_GOLDEN_SAMPLES}}
+<!-- AGENTS-GENERATED:END golden-samples -->
+
+<!-- AGENTS-GENERATED:START setup -->
+## Setup & environment
+{{PLUGIN_JSON_LINE}}
+{{SKILLS_LINE}}
+{{INSTALL_LINE}}
+<!-- AGENTS-GENERATED:END setup -->
+
+<!-- AGENTS-GENERATED:START structure -->
+## Directory structure
+```
+.claude-plugin/
+  plugin.json          → Plugin manifest (name, version, skills)
+skills/
+  <skill-name>/
+    SKILL.md           → Skill definition and instructions
+    assets/            → Templates, reference docs
+    scripts/           → Shell scripts for automation
+    references/        → Examples, golden samples
+```
+<!-- AGENTS-GENERATED:END structure -->
+
+<!-- AGENTS-GENERATED:START commands -->
+## Build & tests
+{{LINT_LINE}}
+{{TEST_LINE}}
+{{VALIDATE_LINE}}
+<!-- AGENTS-GENERATED:END commands -->
+
+<!-- AGENTS-GENERATED:START code-style -->
+## Code style & conventions
+- SKILL.md: Clear, actionable instructions for AI agents
+- Shell scripts: Follow ShellCheck recommendations
+- Templates: Use `{{PLACEHOLDER}}` syntax for variables
+- Keep skills focused on one domain/task
+- Include checkpoints for verification
+- Provide golden samples for pattern demonstration
+<!-- AGENTS-GENERATED:END code-style -->
+
+<!-- AGENTS-GENERATED:START skill-design -->
+## Skill design principles
+- **Actionable**: Tell agents WHAT to do, not just WHAT things are
+- **Verifiable**: Include checkpoints agents can run to verify work
+- **Scoped**: One skill = one domain (don't mix concerns)
+- **Referenced**: Point to golden samples, not generic examples
+- **Minimal**: Include only what agents need; avoid documentation bloat
+<!-- AGENTS-GENERATED:END skill-design -->
+
+<!-- AGENTS-GENERATED:START security -->
+## Security & safety
+- Never include secrets or credentials in skills
+- Validate all user inputs in scripts
+- Use placeholder values in examples: `your-api-key`, `example.com`
+- Review generated content for sensitive information
+<!-- AGENTS-GENERATED:END security -->
+
+<!-- AGENTS-GENERATED:START checklist -->
+## PR/commit checklist
+{{LINT_CHECKLIST_LINE}}
+- [ ] SKILL.md instructions are clear and actionable
+- [ ] Templates use whole-line placeholders (not inline)
+- [ ] Golden samples exist for key patterns
+- [ ] Checkpoints are verifiable
+- [ ] plugin.json version updated if releasing
+<!-- AGENTS-GENERATED:END checklist -->
+
+<!-- AGENTS-GENERATED:START examples -->
+## Patterns to Follow
+> **Prefer looking at real code in this repo over generic examples.**
+> See **Golden Samples** section above for files that demonstrate correct patterns.
+<!-- AGENTS-GENERATED:END examples -->
+
+<!-- AGENTS-GENERATED:START help -->
+## When stuck
+- Check existing skills for patterns
+- Review Claude Code documentation
+- Test skills with `claude --skill <name>`
+- Check root AGENTS.md for project conventions
+<!-- AGENTS-GENERATED:END help -->
+
+## House Rules (project-specific)
+<!-- This section is NOT auto-generated - add your project-specific rules here -->
+{{HOUSE_RULES}}