agent-engineering-skills 1.0.0

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "agent-engineering-skills",
+  "version": "1.0.0",
+  "description": "Modular skills that teach AI agents to audit systems, find bugs, review UX/frontend, and research before reinventing. npx agent-engineering-skills install",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "agent-engineering-skills": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "references/",
+    "templates/",
+    "examples/",
+    "docs/",
+    "scripts/",
+    "AGENTS.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "claude-code",
+    "agent",
+    "skills",
+    "audit",
+    "security",
+    "frontend",
+    "ux",
+    "research",
+    "bug-finding",
+    "ai-agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/1arley/1arley-agent-skills.git"
+  },
+  "bugs": {
+    "url": "https://github.com/1arley/1arley-agent-skills/issues"
+  },
+  "homepage": "https://github.com/1arley/1arley-agent-skills#readme"
+}

package/references/engineering.yaml

@@ -0,0 +1,88 @@
+# references/engineering.yaml
+# Catálogo de fontes para engenharia, arquitetura, concorrência, integridade e bugs.
+# Schema: ver docs/reference-authoring.md
+
+- name: OWASP Cheat Sheet Series
+  url: https://cheatsheetseries.owasp.org/
+  type: methodology
+  category: engineering
+  authority: established
+  use_when:
+    - auditing authentication and authorization flows
+    - reviewing input validation and injection risks
+    - securing session management and error handling
+  avoid_when:
+    - pure frontend visual review
+    - tasks with no security-relevant surface
+  search_queries:
+    - "OWASP cheat sheet authorization"
+    - "OWASP input validation"
+    - "OWASP race condition concurrency"
+
+- name: OWASP Top 10
+  url: https://owasp.org/Top10/
+  type: methodology
+  category: engineering
+  authority: established
+  use_when:
+    - classifying security risks in a web application
+    - prioritizing which audit skills to run
+    - mapping findings to recognized risk categories
+  avoid_when:
+    - mobile-specific or desktop-specific concerns not covered
+    - already-classified, narrow single-issue investigations
+  search_queries:
+    - "OWASP Top 10 broken access control"
+    - "OWASP Top 10 identification authentication failures"
+    - "OWASP security risk categories"
+
+- name: PortSwigger Web Security Academy
+  url: https://portswigger.net/web-security
+  type: methodology
+  category: engineering
+  authority: established
+  use_when:
+    - learning concrete attack patterns for access control and API abuse
+    - finding reproducible exploit examples
+    - training adversarial-review mental models
+  avoid_when:
+    - non-web targets
+    - when a quick checklist suffices
+  search_queries:
+    - "PortSwigger access control vulnerabilities"
+    - "PortSwigger business logic vulnerabilities"
+    - "PortSwigger API testing"
+
+- name: Google Testing Blog
+  url: https://testing.googleblog.com/
+  type: heuristic
+  category: engineering
+  authority: established
+  use_when:
+    - designing edge-case and state-based tests
+    - reasoning about concurrency and flakiness
+    - evaluating testing strategy for race conditions
+  avoid_when:
+    - frontend visual or UX review
+    - operational/infra concerns
+  search_queries:
+    - "Google testing blog flaky tests"
+    - "Google testing blog concurrency"
+    - "testing blog state machine testing"
+
+- name: GitHub
+  url: https://github.com/
+  type: implementation
+  category: engineering
+  authority: community
+  use_when:
+    - searching for production implementations of a pattern
+    - comparing how real projects handle concurrency or idempotency
+    - finding test cases for edge conditions
+  avoid_when:
+    - when official documentation exists and is authoritative
+    - copying code blindly instead of extracting principles
+  search_queries:
+    - "<feature> idempotency implementation"
+    - "<feature> race condition test"
+    - "<feature> transaction integrity"

package/references/frontend.yaml

@@ -0,0 +1,139 @@
+# references/frontend.yaml
+# Catálogo de fontes para frontend: visual, implementação, animação, acessibilidade.
+# Schema: ver docs/reference-authoring.md
+
+- name: Impeccable
+  url: https://impeccable.style/
+  type: heuristic
+  category: frontend
+  authority: established
+  use_when:
+    - reviewing visual quality and craft
+    - auditing spacing, typography, hierarchy, and density
+    - calibrating design taste against a high bar
+  avoid_when:
+    - backend-only tasks
+    - when a strict component spec already exists
+  search_queries:
+    - "impeccable style visual quality"
+    - "impeccable spacing typography hierarchy"
+    - "impeccable frontend craft"
+
+- name: Impeccable Slop
+  url: https://impeccable.style/slop/
+  type: heuristic
+  category: frontend
+  authority: established
+  use_when:
+    - detecting AI slop and generic AI visual patterns
+    - auditing visual-quality-review findings for templated output
+    - training the eye to recognize low-craft generated UI
+  avoid_when:
+    - non-frontend review
+    - when evaluating genuinely bespoke design
+  search_queries:
+    - "impeccable slop AI generated UI patterns"
+    - "detect AI slop frontend"
+    - "generic AI visual patterns"
+
+- name: Interfaces
+  url: https://interfaces.rauno.me/
+  type: heuristic
+  category: frontend
+  authority: curated
+  use_when:
+    - referencing high-craft interaction and visual detail
+    - comparing micro-interaction polish
+    - seeking non-generic UI reference
+  avoid_when:
+    - copying identity or branding
+    - needing prescriptive methodology
+  search_queries:
+    - "interfaces rauno visual detail"
+    - "high craft frontend reference"
+    - "interface polish micro-interactions"
+
+- name: Dribbble
+  url: https://dribbble.com/
+  type: inspiration
+  category: frontend
+  authority: curated
+  use_when:
+    - seeking visual inspiration for composition and style
+    - exploring alternative treatments for a screen
+    - breaking out of generic patterns
+  avoid_when:
+    - using as evidence for a technical finding
+    - copying layouts or branding
+    - any decision requiring authority or methodology
+  search_queries:
+    - "dribbble <screen type> design"
+    - "dribbble dashboard composition"
+    - "dribbble empty state inspiration"
+
+- name: dark.design
+  url: https://www.dark.design/
+  type: inspiration
+  category: frontend
+  authority: curated
+  use_when:
+    - exploring dark-mode and high-contrast visual treatments
+    - seeking non-generic aesthetic direction
+  avoid_when:
+    - using as technical evidence
+    - light-mode or accessibility-contrast requirements
+  search_queries:
+    - "dark design dark mode UI"
+    - "dark design high contrast inspiration"
+    - "dark theme visual reference"
+
+- name: Animate UI
+  url: https://animate-ui.com/
+  type: implementation
+  category: frontend
+  authority: community
+  use_when:
+    - implementing or reviewing concrete animation components
+    - referencing real transition and motion patterns
+    - auditing animation-review findings against working examples
+  avoid_when:
+    - needing animation principles over code
+    - when reduced-motion accessibility is the primary concern
+  search_queries:
+    - "animate ui component animation"
+    - "animate ui transition examples"
+    - "animate ui motion implementation"
+
+- name: LazyWeb
+  url: https://www.lazyweb.com/
+  type: discovery
+  category: frontend
+  authority: community
+  use_when:
+    - discovering more frontend sources and tools
+    - finding what the community is using for a given problem
+    - expanding the reference set before deep research
+  avoid_when:
+    - when authoritative sources are already identified
+    - as primary evidence for a finding
+  search_queries:
+    - "lazyweb frontend tools"
+    - "lazyweb UI libraries"
+    - "lazyweb design resources"
+
+- name: Shoogle
+  url: https://shoogle.dev/
+  type: discovery
+  category: frontend
+  authority: community
+  use_when:
+    - discovering frontend libraries and components
+    - surveying implementation options for a UI need
+    - broadening research before committing to an approach
+  avoid_when:
+    - as primary evidence
+    - when official docs for a chosen library exist
+  search_queries:
+    - "shoogle frontend components"
+    - "shoogle UI library discovery"
+    - "shoogle react components"

package/references/product.yaml

@@ -0,0 +1,54 @@
+# references/product.yaml
+# Catálogo de fontes para produto: regras de negócio, gamificação, comportamento de mercado.
+# Schema: ver docs/reference-authoring.md
+
+- name: GitHub
+  url: https://github.com/
+  type: implementation
+  category: product
+  authority: community
+  use_when:
+    - comparing how real products implement gamification and reward loops
+    - finding production examples of XP, streaks, and achievement systems
+    - locating test cases for reward abuse
+  avoid_when:
+    - copying logic blindly
+    - when official documentation for a framework's reward primitives exists
+  search_queries:
+    - "<product> XP reward implementation"
+    - "gamification streak system github"
+    - "achievement reward loop implementation"
+
+- name: Product Hunt
+  url: https://www.producthunt.com/
+  type: discovery
+  category: product
+  authority: community
+  use_when:
+    - discovering real products that solved a similar problem
+    - surveying how the market approaches a feature
+    - feeding market-research before deeper analysis
+  avoid_when:
+    - as primary evidence for a technical finding
+    - when authoritative methodology is needed
+  search_queries:
+    - "product hunt gamification"
+    - "product hunt <feature category>"
+    - "product hunt reward systems"
+
+- name: Reforge
+  url: https://reforge.com/resources
+  type: methodology
+  category: product
+  authority: established
+  use_when:
+    - reasoning about retention loops and engagement mechanics
+    - auditing whether a reward system is gamed-resistant by design
+    - grounding a gamification-audit in recognized product thinking
+  avoid_when:
+    - pure visual or frontend review
+    - tasks unrelated to engagement or business metrics
+  search_queries:
+    - "Reforge retention loops"
+    - "Reforge gamification mechanics"
+    - "Reforge engagement systems"

package/references/research.yaml

@@ -0,0 +1,88 @@
+# references/research.yaml
+# Catálogo de fontes para pesquisa: descoberta de referências, implementações e mercado.
+# Schema: ver docs/reference-authoring.md
+
+- name: GitHub
+  url: https://github.com/
+  type: implementation
+  category: research
+  authority: community
+  use_when:
+    - searching production implementations of a feature or pattern
+    - comparing architecture, database, API, and framework choices
+    - evaluating activity, quality, tests, docs, adoption, license
+  avoid_when:
+    - when official documentation is more authoritative
+    - copying code instead of extracting ideas
+  search_queries:
+    - "<feature> implementation architecture"
+    - "<feature> database schema API"
+    - "<feature> framework tests adoption"
+
+- name: Google Scholar
+  url: https://scholar.google.com/
+  type: discovery
+  category: research
+  authority: established
+  use_when:
+    - finding authoritative technical literature on a hard problem
+    - grounding concurrency, integrity, or algorithm decisions in research
+    - when uncertainty and impact are both high
+  avoid_when:
+    - routine implementation tasks
+    - when practitioner sources already answer the question
+  search_queries:
+    - "<topic> race condition formal"
+    - "<topic> idempotency distributed systems"
+    - "<topic> consensus integrity"
+
+- name: Hacker News
+  url: https://news.ycombinator.com/
+  type: discovery
+  category: research
+  authority: community
+  use_when:
+    - finding practitioner discussion and post-mortems
+    - discovering real-world edge cases and failures
+    - surveying community sentiment on a library or approach
+  avoid_when:
+    - as primary technical evidence
+    - when authoritative docs exist
+  search_queries:
+    - "Hacker News <library> experience"
+    - "Hacker News <feature> post-mortem"
+    - "Hacker News <pattern> pitfalls"
+
+- name: Stack Overflow
+  url: https://stackoverflow.com/
+  type: heuristic
+  category: research
+  authority: community
+  use_when:
+    - finding how practitioners solved a specific technical problem
+    - locating known edge cases and gotchas
+    - debugging an obscure error during investigation
+  avoid_when:
+    - when official documentation covers the topic
+    - as justification for a security finding
+  search_queries:
+    - "<error message> stack overflow"
+    - "<library> <edge case>"
+    - "<pattern> concurrency gotcha"
+
+- name: DevDocs
+  url: https://devdocs.io/
+  type: implementation
+  category: research
+  authority: vendor
+  use_when:
+    - quickly consulting consolidated official documentation
+    - cross-referencing API references across frameworks
+    - during implementation-research for canonical signatures
+  avoid_when:
+    - when the vendor's own docs have fuller guides
+    - non-documented, behavioral questions
+  search_queries:
+    - "devdocs <framework> api reference"
+    - "devdocs <method> signature"
+    - "devdocs <library> documentation"

package/references/security.yaml

@@ -0,0 +1,85 @@
+# references/security.yaml
+# Catálogo de fontes para segurança: autorização, abuso de API, confiança de input.
+# Schema: ver docs/reference-authoring.md
+
+- name: OWASP Cheat Sheet Series
+  url: https://cheatsheetseries.owasp.org/
+  type: methodology
+  category: security
+  authority: established
+  use_when:
+    - auditing authorization and access control
+    - reviewing input validation and trust boundaries
+    - designing server-side enforcement of permissions
+  avoid_when:
+    - pure UX or visual review
+    - non-web security contexts
+  search_queries:
+    - "OWASP authorization cheat sheet"
+    - "OWASP injection prevention"
+    - "OWASP server-side validation"
+
+- name: OWASP Top 10
+  url: https://owasp.org/Top10/
+  type: methodology
+  category: security
+  authority: established
+  use_when:
+    - classifying authorization and input-trust findings
+    - prioritizing security skill selection
+    - mapping defects to Broken Access Control / Identification & Auth Failures
+  avoid_when:
+    - narrow investigations already scoped to one issue
+  search_queries:
+    - "OWASP broken access control A01"
+    - "OWASP identification authentication A07"
+    - "OWASP security by design"
+
+- name: PortSwigger Web Security Academy
+  url: https://portswigger.net/web-security
+  type: methodology
+  category: security
+  authority: established
+  use_when:
+    - reproducing access control and API abuse attack patterns
+    - learning IDOR and privilege escalation techniques
+    - training input-trust adversarial thinking
+  avoid_when:
+    - non-web targets
+  search_queries:
+    - "PortSwigger access control"
+    - "PortSwigger IDOR insecure direct object reference"
+    - "PortSwigger API abuse mass assignment"
+
+- name: CWE — Common Weakness Enumeration
+  url: https://cwe.mitre.org/
+  type: heuristic
+  category: security
+  authority: established
+  use_when:
+    - naming and classifying a confirmed weakness
+    - finding canonical descriptions of input-trust and authorization flaws
+    - referencing a finding to a recognized standard
+  avoid_when:
+    - discovery of novel patterns (CWE classifies known ones)
+  search_queries:
+    - "CWE authorization missing"
+    - "CWE improper input validation"
+    - "CWE trust boundary violation"
+
+- name: GitHub
+  url: https://github.com/
+  type: implementation
+  category: security
+  authority: community
+  use_when:
+    - finding real-world examples of authorization middleware
+    - comparing how projects enforce ownership and roles server-side
+    - locating test suites for access control
+  avoid_when:
+    - when official guidance is more authoritative
+    - copying middleware blindly without adapting to the project's model
+  search_queries:
+    - "<framework> authorization middleware"
+    - "<framework> role based access control implementation"
+    - "<feature> ownership check server side"

package/references/ux.yaml

@@ -0,0 +1,37 @@
+# references/ux.yaml
+# Catálogo de fontes para UX: usabilidade, heurísticas, fluxos, carga cognitiva.
+# Schema: ver docs/reference-authoring.md
+
+- name: Laws of UX
+  url: https://lawsofux.com/
+  type: methodology
+  category: ux
+  authority: established
+  use_when:
+    - reviewing usability and cognitive load
+    - designing or auditing user flows
+    - justifying a UX decision with a recognized principle
+  avoid_when:
+    - pure visual or aesthetic review
+    - backend-only tasks
+  search_queries:
+    - "Laws of UX heuristics"
+    - "Laws of UX cognitive load"
+    - "Laws of UX Hick's law Fitts's law"
+
+- name: Interfaces
+  url: https://interfaces.rauno.me/
+  type: heuristic
+  category: ux
+  authority: curated
+  use_when:
+    - calibrating taste for interaction detail and feedback
+    - comparing affordances and micro-interactions
+    - seeking reference for high-craft interface patterns
+  avoid_when:
+    - needing authoritative methodology
+    - copying visual identity
+  search_queries:
+    - "interfaces rauno interaction detail"
+    - "high craft UI affordances"
+    - "interface micro-interactions reference"