builtin-agent-skill

## When to Use - Adding a first-class attack technique the agent classifies and follows a workflow for. For a user-uploadable workflow, use `add-community-skill` instead. For a *tool* the agent calls, use `agentic-tool-integration`. For per-skill tunable defaults, use `project-settings-cascade`. --- ## Critical Rules - **ALWAYS add the skill id to `KNOWN_ATTACK_PATHS`** in [agentic/state.py](../../agentic/state.py). It is the Pydantic validator's allowlist; miss it and the classifier's output is **rejected at runtime** even though every other layer is wired. - **NEVER skip layers 8 and 9** (the chat-drawer layers). They live in webapp and produce **no error** when forgotten: the skill classifies and badges, but the drawer tooltip and one-click example prompts are silently missing. Layer 8 = `BUILT_IN_SKILLS` in [attack-skills/available/route.ts](../../webapp/src/app/api/users/[id]/attack-skills/available/route.ts); Layer 9 = a `SESubGroup` in [suggestionData.ts](../../webapp/src/app/graph/components/AIAssistantDrawer/suggestionData.ts). - **NEVER let classification keywords overlap an existing skill.** Every enabled built-in competes for the same user message; overlapping keywords (e.g. saying "SQL" in an SSRF section) make both skills mis-route. Disambiguate in the "Key distinction" line of the section in [classification.py](../../agentic/prompts/classification.py). - **ALWAYS gate the workflow on the required tool** inside `_inject_builtin_skill_workflow()` ([agentic/prompts/__init__.py:509](../../agentic/prompts/__init__.py#L509)): `and "<tool>" in allowed_tools`. Without the guard the agent gets instructions for a tool `TOOL_PHASE_MAP` blocks in that phase. - **NEVER assume existing projects inherit the new skill.** `builtIn` is a strict has-key check; existing projects need a jsonb update to `attackSkillConfig`. - **ALWAYS add a registry entry for a per-skill tunable that became a `Project` column** in [recon_settings/registry.yaml](../../recon_settings/registry.yaml). A test walking `Prisma.ProjectScalarFieldEnum` fails until every column has one. Draft it with `python3 tooling/scripts/extract_recon_registry.py`, edit it, then `python3 recon_settings/build.py`. An attack-skill tunable is ordinary `mcp: settable` tuning now, bounded by its registry entry and gated at scan start by `roeForbiddenCategories`, `roeForbiddenTools` and `roeAllowDos` rather than by being unreachable. Give it `traffic: active` so it joins the queued-job fingerprint, and `roe_capped: true` if its unit is `rps`. - **Pick the snake_case id once and use that exact literal in all 9 layers.** `grep -rn "<skill_id>" webapp/src agentic` must show it everywhere before you rebuild (an existing id like `cve_exploit` spans ~38 files). --- ## The nine layers (all required end to end) | # | Layer | File | | --- | --- | --- | | 1 | Workflow prompt | `agentic/prompts/<skill_id>_prompts.py` | | 2 | Package re-export + `__all__` | [agentic/prompts/__init__.py](../../agentic/prompts/__init__.py) | | 3 | Phase injection branch | `_inject_builtin_skill_workflow()` (same file) | | 4 | Classification + validator | [classification.py](../../agentic/prompts/classification.py) `_BUILTIN_SKILL_MAP` **and** `KNOWN_ATTACK_PATHS` in [state.py](../../agentic/state.py) | | 5 | Settings default | `ATTACK_SKILL_CONFIG.builtIn` in [agentic/project_settings.py](../../agentic/project_settings.py) | | 6 | Prisma default | `attackSkillConfig` JSON in [schema.prisma](../../webapp/prisma/schema.prisma) | | 7 | UI toggle + badge | [AttackSkillsSection.tsx](../../webapp/src/components/projects/ProjectForm/sections/AttackSkillsSection.tsx) + [phaseConfig.ts](../../webapp/src/app/graph/components/AIAssistantDrawer/phaseConfig.ts) | | 8 | Drawer tooltip | [attack-skills/available/route.ts](../../webapp/src/app/api/users/[id]/attack-skills/available/route.ts) `BUILT_IN_SKILLS` | | 9 | Drawer example prompts | [suggestionData.ts](../../webapp/src/app/graph/components/AIAssistantDrawer/suggestionData.ts) | ## Commands ```bash docker compose build agent && docker compose up -d agent # agentic/ is baked docker compose exec webapp npx prisma db push # NEVER prisma migrate # verify the id is wired everywhere before rebuild: grep -rn "<skill_id>" webapp/src agentic ``` ## Resources - [docs/readmes/coding_agent_prompts/PROMPT.ADD_BUILTIN_AGENT_SKILL.md](../../docs/readmes/coding_agent_prompts/PROMPT.ADD_BUILTIN_AGENT_SKILL.md) - full per-layer walkthrough, tunable-design patterns, failure triage - Related skills: `agentic-tool-integration`, `project-settings-cascade`, `add-community-skill`