From 3d0a41e5b6c29a5fa6e2a4b5144cd0f9c3c75c2f Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Wed, 27 May 2026 17:35:11 +0000 Subject: [PATCH] feat(skills): add codacy agent skill and configuration - Implement Codacy skill in .agents/skills/codacy with SKILL.md and evaluation cases - Add .codacy.yaml configuration tailored for TypeScript/Vite project - Register skill symlinks for Claude, Gemini, and Qwen agents - Update central documentation and agents registry via automated scripts - Add missing Available Skills section to root AGENTS.md for validation compliance Co-authored-by: d-oit <6849456+d-oit@users.noreply.github.com> --- .agents/skills/README.md | 2 + .agents/skills/codacy/SKILL.md | 71 +++++++++++++++++++ .agents/skills/codacy/evals/evals.json | 39 ++++++++++ .../skills/codacy/references/config-format.md | 34 +++++++++ .../skills/codacy/references/output-format.md | 27 +++++++ .../codacy/references/supported-tools.md | 21 ++++++ .claude/skills/codacy | 1 + .codacy.yaml | 28 ++++++++ .gemini/skills/codacy | 1 + .qwen/skills/codacy | 1 + AGENTS.md | 58 +++++++++++++++ agents-docs/AGENTS.md | 3 +- agents-docs/AVAILABLE_SKILLS.md | 7 ++ 13 files changed, 292 insertions(+), 1 deletion(-) create mode 100644 .agents/skills/codacy/SKILL.md create mode 100644 .agents/skills/codacy/evals/evals.json create mode 100644 .agents/skills/codacy/references/config-format.md create mode 100644 .agents/skills/codacy/references/output-format.md create mode 100644 .agents/skills/codacy/references/supported-tools.md create mode 120000 .claude/skills/codacy create mode 100644 .codacy.yaml create mode 120000 .gemini/skills/codacy create mode 120000 .qwen/skills/codacy diff --git a/.agents/skills/README.md b/.agents/skills/README.md index a543685..cdbff80 100644 --- a/.agents/skills/README.md +++ b/.agents/skills/README.md @@ -47,6 +47,7 @@ Validate symlinks are intact: | [`atomic-commit/`](atomic-commit/) | Atomic git workflow - validates, commits, pushes, creates PR, and verifies CI with zero-warnings policy. Orchestrates complete code submission as state machine with rollback on failure. | | [`cicd-pipeline/`](cicd-pipeline/) | Design and implement CI/CD pipelines with GitHub Actions, GitLab CI, and Forgejo Actions. Use for automated testing, deployment strategies (blue-green, canary), security scanning, and multi-environment workflows. Includes pipeline optimization, secrets management, and failure handling patterns. | | [`cloudflare-worker-api/`](cloudflare-worker-api/) | Structure Worker API routes and handlers. Activate for route definition, response helpers, and typed handler patterns. Auth belongs to secure-invite-and-access. | +| [`codacy/`](codacy/) | Use Codacy static analysis CLIs to query PR analysis, triage issues, suppress false positives, and run local analysis. Use when Codacy blocks a PR, when asked to fix Codacy issues, suppress false positives, query PR quality data, or integrate Codacy into CI/CD workflows. Also use when the user mentions "Codacy", "static analysis check", "code quality gate", or "Codacy is failing". | | [`code-quality/`](code-quality/) | Review and improve code quality across any programming language. Use when conducting code reviews, refactoring for best practices, identifying code smells, or improving maintainability. | | [`code-review-assistant/`](code-review-assistant/) | Automated code review with PR analysis, change summaries, and quality checks. Use for reviewing pull requests, generating review comments, checking against best practices, and identifying potential issues. Includes style guide compliance, security issue detection, and review automation. | | [`codeberg-api/`](codeberg-api/) | Interact with Forgejo/Codeberg repositories via the REST API — read or write files, manage issues, create pull requests, list branches/tags, search repos, and automate CI/CD workflows. Use this skill when the user wants to: read file contents from a Forgejo repo, create or update files, manage issues (create, list, close), list repositories for a user, search, set up Forgejo Actions workflows, or automate any git-forge operation. Works without authentication for public repos; requires FORGEJO_TOKEN for private repos and write operations. | @@ -62,6 +63,7 @@ Validate symlinks are intact: | [`goap-agent/`](goap-agent/) | Invoke for complex multi-step tasks requiring intelligent planning and multi-agent coordination. Use when tasks need decomposition, dependency mapping, parallel/sequential/swarm/iterative execution strategies, or coordination of multiple specialized agents with quality gates. | | [`intent-classifier/`](intent-classifier/) | Classify user intents and route to appropriate skills, commands, or workflows. Use when determining which skill to invoke, routing requests to specialized agents, or building skill selection logic. Trigger on 'which skill should I use', 'route this to', 'classify this request', 'skill selection', or when multiple skills could handle a task. | | [`iterative-refinement/`](iterative-refinement/) | Execute iterative refinement workflows with validation loops until quality criteria are met. Use for test-fix cycles, code quality improvement, performance optimization, or any task requiring repeated action-validate-improve cycles. | +| [`jules/`](jules/) | Autonomous Jules Delegator skill for delegating complex, multi-file tasks to a persistent repository-aware session. | | [`jules-implement/`](jules-implement/) | Repository-aware implementation agent that handles delta-based targeted research, code generation, and validation of Stitch-rendered designs. | | [`learn/`](learn/) | Extract non-obvious session learnings into scoped AGENTS.md files | | [`local-chat-policy/`](local-chat-policy/) | Guidelines for ensuring chat functionality prioritizes local data and respects privacy. | diff --git a/.agents/skills/codacy/SKILL.md b/.agents/skills/codacy/SKILL.md new file mode 100644 index 0000000..16981b5 --- /dev/null +++ b/.agents/skills/codacy/SKILL.md @@ -0,0 +1,71 @@ +--- +name: codacy +version: 1.0.0 +description: Use Codacy static analysis CLIs to query PR analysis, triage issues, suppress false positives, and run local analysis. Use when Codacy blocks a PR, when asked to fix Codacy issues, suppress false positives, query PR quality data, or integrate Codacy into CI/CD workflows. Also use when the user mentions "Codacy", "static analysis check", "code quality gate", or "Codacy is failing". +category: Quality +license: MIT +metadata: + author: d-oit + version: 1.0.0 +--- +# Codacy Static Analysis + +Orchestrate static analysis using Codacy Analysis CLI (local) and Codacy Cloud CLI (remote). + +## Installation & Auth + +```bash +npm i -g @codacy/analysis-cli @codacy/codacy-cloud-cli +export CODACY_API_TOKEN= +``` + +## PR Triage Workflow + +1. **Get PR analysis**: + `codacy pull-request gh --output json > /tmp/codacy-pr.json` + +2. **Categorize issues**: + - False positives → Suppress via Cloud CLI. + - Real issues → Fix in code. + +3. **Suppress false positives**: + `codacy pull-request gh --ignore-issue --ignore-reason FalsePositive` + *Note: Use numeric `resultDataId`, NOT hash IDs.* + +4. **Fix issues**: Batch fix patterns and verify with local lint/tests (`pnpm run lint`, `pnpm run quality_gate`). + +## Local Analysis + +```bash +codacy-analysis init --default +codacy-analysis analyze --pr --output-format json +``` + +## Known Limitations + +| Tool Category | Status | Note | +|---------------|--------|------| +| JS/TS/Shell | ✅ Works | ESLint9, Stylelint, ShellCheck | +| Python/Ruby | ❌ Fails | Missing runtimes/venv issues | +| Java/PMD | ❌ Fails | Missing Java runtime | + +Always cross-reference with Cloud CLI for full PR data. + +## Rationalizations + +| Rationalization | Reality | +|-----------------|---------| +| "Local analysis shows 0 issues, so we are good." | Analysis CLI has limited local tool support; Cloud CLI is the source of truth. | +| "I'll use the issue hash for suppression." | Codacy CLI requires the numeric `resultDataId` for suppressions. | + +## Red Flags + +- [ ] Relying solely on local `codacy-analysis` for Python/Java projects. +- [ ] Attempting to suppress issues without a valid `--ignore-reason`. +- [ ] Ignoring the `resultDataId` field in JSON output in favor of hashes. + +## References + +- `references/output-format.md` - JSON schema for PR analysis +- `references/supported-tools.md` - Local vs Cloud tool availability +- `references/config-format.md` - `.codacy.yaml` schema diff --git a/.agents/skills/codacy/evals/evals.json b/.agents/skills/codacy/evals/evals.json new file mode 100644 index 0000000..93b3110 --- /dev/null +++ b/.agents/skills/codacy/evals/evals.json @@ -0,0 +1,39 @@ +{ + "skill_name": "codacy", + "version": "1.0.0", + "evals": [ + { + "id": 1, + "prompt": "Codacy is blocking PR #209 on d-o-hub/do-knowledge-studio. How do I find out what issues exist?", + "expected_output": "Uses `codacy pull-request ... --output json` to fetch the PR data, parses the `newIssues` array to identify blockers, and checks the `qualityGateStatus` field.", + "assertions": [ + "Uses `codacy pull-request ... --output json`", + "Mentions parsing newIssues array", + "Mentions checking quality gate status" + ], + "files": [] + }, + { + "id": 2, + "prompt": "I have a false positive from SQLint about VIRTUAL in my SQL migration. How do I suppress it?", + "expected_output": "Identifies the numeric `resultDataId` from the JSON output (not the hash), and runs `codacy pull-request gh --ignore-issue --ignore-reason FalsePositive`.", + "assertions": [ + "Mentions numeric resultDataId from JSON", + "Uses --ignore-issue with the numeric ID", + "Specifies --ignore-reason FalsePositive" + ], + "files": [] + }, + { + "id": 3, + "prompt": "I ran codacy-analysis locally but it shows 0 issues. Cloud shows 86. What's wrong?", + "expected_output": "Explains that the Analysis CLI is limited to a subset of tools (like ESLint, ShellCheck) and often fails on Python, Ruby, or Java tools due to missing runtimes. Recommends using the Cloud CLI for accurate PR data.", + "assertions": [ + "Mentions Analysis CLI limitation (subset of tools)", + "Notes that Python/Ruby/Java tools may fail locally", + "Suggests using Cloud CLI for authoritative data" + ], + "files": [] + } + ] +} diff --git a/.agents/skills/codacy/references/config-format.md b/.agents/skills/codacy/references/config-format.md new file mode 100644 index 0000000..99ab1a0 --- /dev/null +++ b/.agents/skills/codacy/references/config-format.md @@ -0,0 +1,34 @@ +# Codacy Configuration Format + +Codacy can be configured via a `.codacy.yaml` file in the repository root. + +## Schema + +```yaml +--- +engines: + eslint-9: + exclude_paths: + - "dist/**" + - "coverage/**" + duplication: + exclude_paths: + - "dist/**" + - "coverage/**" + config: + languages: + - "typescript" + - "javascript" +exclude_paths: + - "dist/**" + - "coverage/**" + - "**/node_modules/**" +``` + +## Local Initialization + +You can generate a default configuration using: + +```bash +codacy-analysis init --default +``` diff --git a/.agents/skills/codacy/references/output-format.md b/.agents/skills/codacy/references/output-format.md new file mode 100644 index 0000000..1230607 --- /dev/null +++ b/.agents/skills/codacy/references/output-format.md @@ -0,0 +1,27 @@ +# Codacy PR Analysis Output Format + +The `codacy pull-request` command with `--output json` produces a JSON object containing analysis results. + +## Key Fields + +- `newIssues`: Array of issues introduced in the PR. +- `fixedIssues`: Array of issues resolved in the PR. +- `qualityGateStatus`: `Passed`, `Warning`, or `Failed`. + +## Issue Object Schema + +```json +{ + "resultDataId": 123456789, + "hash": "abc123def456...", + "message": "Avoid using 'eval()'", + "file": "src/app.js", + "line": 42, + "tool": "ESLint", + "severity": "Critical" +} +``` + +### Important: resultDataId + +When suppressing issues via the CLI (e.g., `--ignore-issue`), you **MUST** use the numeric `resultDataId`. The `hash` string is used for identification in the UI but is NOT supported by the suppression command. diff --git a/.agents/skills/codacy/references/supported-tools.md b/.agents/skills/codacy/references/supported-tools.md new file mode 100644 index 0000000..78cbd29 --- /dev/null +++ b/.agents/skills/codacy/references/supported-tools.md @@ -0,0 +1,21 @@ +# Supported Codacy Tools + +Codacy supports hundreds of tools, but only a subset are available in the local Analysis CLI. + +## Local Analysis CLI Support + +| Tool | Language | Status | +|------|----------|--------| +| ESLint9 | JavaScript/TypeScript | ✅ Supported | +| Stylelint | CSS/SCSS | ✅ Supported | +| ShellCheck | Shell | ✅ Supported | +| Trivy | Security/IAC | ✅ Supported | +| markdownlint | Markdown | ✅ Supported | +| Bandit | Python | ❌ Fails (venv) | +| Pylint | Python | ❌ Fails (venv) | +| SQLint | SQL | ❌ Fails (Ruby) | +| PMD | Java | ❌ Fails (Java) | + +## Cloud Analysis + +The Codacy Cloud (Remote) analysis runs all enabled tools in the Codacy dashboard regardless of local runtime availability. Always use `codacy pull-request` to see the full list of issues. diff --git a/.claude/skills/codacy b/.claude/skills/codacy new file mode 120000 index 0000000..c04bde2 --- /dev/null +++ b/.claude/skills/codacy @@ -0,0 +1 @@ +../../.agents/skills/codacy \ No newline at end of file diff --git a/.codacy.yaml b/.codacy.yaml new file mode 100644 index 0000000..5024ef4 --- /dev/null +++ b/.codacy.yaml @@ -0,0 +1,28 @@ +--- +engines: + eslint-8: + exclude_paths: + - "dist/**" + - "coverage/**" + - "export/**" + duplication: + exclude_paths: + - "dist/**" + - "coverage/**" + - "export/**" + - "tests/**" + config: + languages: + - "typescript" + - "javascript" +exclude_paths: + - "dist/**" + - "coverage/**" + - "export/**" + - "**/node_modules/**" + - ".agents/**" + - ".claude/**" + - ".gemini/**" + - ".qwen/**" + - ".cursor/**" + - ".windsurf/**" diff --git a/.gemini/skills/codacy b/.gemini/skills/codacy new file mode 120000 index 0000000..c04bde2 --- /dev/null +++ b/.gemini/skills/codacy @@ -0,0 +1 @@ +../../.agents/skills/codacy \ No newline at end of file diff --git a/.qwen/skills/codacy b/.qwen/skills/codacy new file mode 120000 index 0000000..c04bde2 --- /dev/null +++ b/.qwen/skills/codacy @@ -0,0 +1 @@ +../../.agents/skills/codacy \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 6aec2dd..b2d1e88 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -221,3 +221,61 @@ Before marking a task done: - No temp, scratch, analysis, or one-off script files were added to the repository root. - Lint, typecheck, tests, and build pass. - Relevant docs or learnings were updated and compacted if the task produced durable new guidance. + +### Available Skills + +| Skill | Description | Category | +|-------|-------------|----------| +| `accessibility-auditor` | Audit web applications for WCAG 2.2 compliance, screen reade | Security | +| `agent-browser` | Browser automation CLI for AI agents. Use when the user need | workflow | +| `agent-coordination` | Coordinate multiple agents for software development across a | Coordination | +| `agents-md` | Create AGENTS.md files with production-ready best practices. | General | +| `anti-ai-slop` | > | General | +| `api-design-first` | Design and document RESTful APIs using design-first principl | API Development | +| `architecture-diagram` | Generate or update a project architecture SVG diagram by sca | General | +| `atomic-commit` | Atomic git workflow - validates, commits, pushes, creates PR | General | +| `cicd-pipeline` | Design and implement CI/CD pipelines with GitHub Actions, Gi | DevOps | +| `cloudflare-worker-api` | > | workflow | +| `codacy` | Use Codacy static analysis CLIs to query PR analysis, triage | Quality | +| `code-quality` | Review and improve code quality across any programming langu | Quality | +| `code-review-assistant` | Automated code review with PR analysis, change summaries, an | General | +| `codeberg-api` | >- | API Development | +| `database-devops` | Database design, migration, and DevOps automation with safet | DevOps | +| `database-schema-migrations` | > | workflow | +| `do-web-doc-resolver` | Python resolver for URLs and queries into compact, LLM-ready | Documentation | +| `docs-hook` | Lightweight git hook integration for updating agents-docs wi | Documentation | +| `document-rendering-and-locators` | > | workflow | +| `dogfood` | Systematically explore and test a web application to find bu | quality | +| `git-github-workflow` | Unified atomic git workflow with GitHub integration - commit | General | +| `github-readme` | Create human-focused GitHub README.md files with 2026 best p | Documentation | +| `github-workflow` | Complete GitHub workflow automation - push, create branch/PR | General | +| `goap-agent` | Invoke for complex multi-step tasks requiring intelligent pl | Coordination | +| `intent-classifier` | Classify user intents and route to appropriate skills, comma | Coordination | +| `iterative-refinement` | Execute iterative refinement workflows with validation loops | General | +| `jules` | > | General | +| `jules-implement` | > | General | +| `learn` | Extract non-obvious session learnings into scoped AGENTS.md | knowledge-management | +| `local-chat-policy` | Guidelines for ensuring chat functionality prioritizes local | General | +| `memory-context` | Retrieve semantically relevant past learnings and analysis o | General | +| `migration-refactoring` | Automate complex code migrations and refactorings with safet | Migration | +| `parallel-execution` | Execute multiple independent tasks simultaneously using para | Coordination | +| `privacy-first` | > | Security | +| `pwa-offline-sync` | > | workflow | +| `reader-ui-ux` | > | workflow | +| `secure-invite-and-access` | > | workflow | +| `security-code-auditor` | Perform security audits on code to identify vulnerabilities, | Security | +| `self-fix-loop` | Self-learning fix loop - commit, push, monitor CI, auto-fix | General | +| `shell-script-quality` | Lint and test shell scripts using ShellCheck and BATS. Use w | Quality | +| `skill-creator` | Create new skills, modify and improve existing skills, and m | Meta | +| `skill-evaluator` | Reusable skill for evaluating other skills with structure ch | Meta | +| `stitch-design` | > | General | +| `task-decomposition` | Break down complex tasks into atomic, actionable goals with | Coordination | +| `test-runner` | Execute tests, analyze results, and diagnose failures across | Quality | +| `testdata-builders` | > | quality | +| `testing-strategy` | Design comprehensive testing strategies with modern techniqu | Quality | +| `triz-analysis` | Run a systematic TRIZ contradiction audit against a codebase | analysis | +| `triz-solver` | Systematic problem-solving using TRIZ (Theory of Inventive P | innovation-problem-solving | +| `turso-db` | Use this skill for Turso (LibSQL/Limbo) database development | DevOps | +| `ui-ux-optimize` | > | UI/UX | +| `validation-checklist` | Maintain high data quality and schema adherence within the k | Quality | +| `web-search-researcher` | Research topics using web search to find accurate, current i | Research | diff --git a/agents-docs/AGENTS.md b/agents-docs/AGENTS.md index 0cb6a19..76e235a 100644 --- a/agents-docs/AGENTS.md +++ b/agents-docs/AGENTS.md @@ -1,7 +1,7 @@ # Agents Registry > Auto-generated registry of all sub-agents in this repository. -> Last updated: 2026-05-19 10:39 UTC +> Last updated: 2026-05-27 17:21 UTC This file provides a centralized discovery mechanism for all available sub-agents. Agents are organized by CLI tool and purpose. @@ -39,6 +39,7 @@ See [`agents-docs/AVAILABLE_SKILLS.md`](agents-docs/AVAILABLE_SKILLS.md) for aut | `atomic-commit` | `.agents/skills/atomic-commit` | Atomic git workflow - validates, commits, pushes, creates PR | | `cicd-pipeline` | `.agents/skills/cicd-pipeline` | Design and implement CI/CD pipelines with GitHub Actions, Gi | | `cloudflare-worker-api` | `.agents/skills/cloudflare-worker-api` | Structure Worker API routes and handlers. Activate for route | +| `codacy` | `.agents/skills/codacy` | Use Codacy static analysis CLIs to query PR analysis, triage | | `code-quality` | `.agents/skills/code-quality` | Review and improve code quality across any programming langu | | `code-review-assistant` | `.agents/skills/code-review-assistant` | Automated code review with PR analysis, change summaries, an | | `codeberg-api` | `.agents/skills/codeberg-api` | Interact with Forgejo/Codeberg repositories via the REST API | diff --git a/agents-docs/AVAILABLE_SKILLS.md b/agents-docs/AVAILABLE_SKILLS.md index 8039cb0..ee8cb7d 100644 --- a/agents-docs/AVAILABLE_SKILLS.md +++ b/agents-docs/AVAILABLE_SKILLS.md @@ -3,6 +3,12 @@ > Auto-generated from skill definitions in `.agents/skills/` > Do not edit manually. Run `./scripts/generate-available-skills.sh` to regenerate. +## Quality + +| Skill | Description | +|-------|-------------| +| `codacy` | Use Codacy static analysis CLIs to query PR analysis, triage issues, suppress false positives, and run local analysis. Use when Codacy blocks a PR, when asked to fix Codacy issues, suppress false positives, query PR quality data, or integrate Codacy into CI/CD workflows. Also use when the user mentions "Codacy", "static analysis check", "code quality gate", or "Codacy is failing". | + ## Analysis | Skill | Description | @@ -33,6 +39,7 @@ | `goap-agent` | Invoke for complex multi-step tasks requiring intelligent planning and multi-agent coordination. Use when tasks need decomposition, dependency mapping, parallel/sequential/swarm/iterative execution strategies, or coordination of multiple specialized agents with quality gates. | | `intent-classifier` | Classify user intents and route to appropriate skills, commands, or workflows. Use when determining which skill to invoke, routing requests to specialized agents, or building skill selection logic. Trigger on 'which skill should I use', 'route this to', 'classify this request', 'skill selection', or when multiple skills could handle a task. | | `iterative-refinement` | Execute iterative refinement workflows with validation loops until quality criteria are met. Use for test-fix cycles, code quality improvement, performance optimization, or any task requiring repeated action-validate-improve cycles. | +| `jules` | Autonomous Jules Delegator skill for delegating complex, multi-file tasks to a persistent repository-aware session. | | `jules-implement` | Repository-aware implementation agent that handles delta-based targeted research, code generation, and validation of Stitch-rendered designs. | | `local-chat-policy` | Guidelines for ensuring chat functionality prioritizes local data and respects privacy. | | `memory-context` | Retrieve semantically relevant past learnings and analysis outputs using the csm CLI (HDC encoder with hybrid BM25 retrieval) |