Embedded Skills

Built-in Skills

Tavily Research Skill

The tavily-research skill demonstrates the async two-tool pattern for long-running operations:

forge skills add tavily-research

This registers two tools:

The LLM uses them in sequence: submit the research request, inform the user that research is in progress, then call the poll tool which handles all waiting internally. The complete report (1000-3000 words with sources) is returned to the LLM and delivered to the user.

Research models:

Requires: curl, jq, TAVILY_API_KEY environment variable.

Kubernetes Incident Triage Skill

The k8s-incident-triage skill performs read-only triage of Kubernetes workloads using kubectl:

forge skills add k8s-incident-triage

This registers a single tool:

The skill accepts two input modes:

• Human mode — natural language like "triage payments-prod" or "why are pods pending in checkout-prod?"
• Automation mode — structured JSON with namespace, workload, pod, and diagnostic options

Triage process:

1. Verify cluster access (kubectl version, cluster-info)
2. Fast health snapshot (pods, deployments, statefulsets)
3. Events timeline (FailedScheduling, probe failures, evictions)
4. Describe pods & workloads (container state, restart counts, probes)
5. Node diagnostics (optional — NotReady, memory/disk pressure)
6. Logs (optional — with previous container logs for CrashLoopBackOff)
7. Metrics (optional — via metrics-server)

Detection heuristics classify issues into: CrashLoop, OOMKilled, Image Pull Failure, Scheduling Constraint, Probe Failure, PVC/Volume Failure, Node Pressure/Eviction, Rollout Stuck. Each finding includes a hypothesis, evidence, confidence score (0.0-1.0), and recommended next commands.

Safety: This skill is strictly read-only. It never executes apply, patch, delete, exec, port-forward, scale, or rollout restart. It never prints Secret values.

Requires: kubectl, optional KUBECONFIG, K8S_API_DOMAIN, DEFAULT_NAMESPACE environment variables.

Kubernetes Pod Rightsizer Skill

The k8s-pod-rightsizer skill analyzes real workload metrics (Prometheus or metrics-server fallback) and produces policy-constrained CPU/memory rightsizing recommendations:

forge skills add k8s-pod-rightsizer

This skill operates in three modes:

Key features:

• Deterministic formulas — no LLM-based guessing for recommendations
• Policy model with per-namespace and per-workload overrides (safety factors, min/max bounds, step constraints)
• Prometheus p95 metrics with metrics-server fallback
• Automatic rollback bundle generation in apply mode
• Workload classification: over-provisioned, under-provisioned, right-sized, limit-bound, insufficient-data

Apply workflow: The skill's built-in mode=apply handles rollback bundles, strategic merge patches via kubectl patch, and rollout verification. Do not manually run kubectl apply -f — use mode=apply with i_accept_risk: true instead.

Requires: bash, kubectl, jq, curl. Optional: KUBECONFIG, K8S_API_DOMAIN, PROMETHEUS_URL, PROMETHEUS_TOKEN, POLICY_FILE, DEFAULT_NAMESPACE.

Kubernetes Cost Visibility Skill

The k8s-cost-visibility skill estimates Kubernetes infrastructure costs by querying cluster node, pod, PVC/PV, and LoadBalancer data via kubectl, applying cloud pricing models, and producing cost attribution reports:

forge skills add k8s-cost-visibility

This registers a single tool:

Cost dimensions tracked:

Grouping modes: namespace (includes storage + LB columns), workload, node, label:<key>, annotation:<key>.

Pricing modes: auto (detect cloud CLI), aws, gcp, azure, static (built-in rates), custom:<file.json> (user-provided rates).

Safety: This skill is strictly read-only. It only uses kubectl get commands (nodes, pods, pvc, pv, svc) — never apply, delete, patch, exec, or scale.

Requires: kubectl, jq, awk, bc. Optional: KUBECONFIG, K8S_API_DOMAIN, DEFAULT_NAMESPACE, AWS_REGION, AZURE_SUBSCRIPTION_ID, GCP_PROJECT.

Codegen React Skill

The codegen-react skill scaffolds and iterates on Vite + React applications with Tailwind CSS:

forge skills add codegen-react

This registers four tools:

Iteration workflow:

1. Scaffold the project with codegen_react_scaffold
2. Start the dev server with codegen_react_run — installs deps, opens browser
3. Read/write files with codegen_react_read / codegen_react_write — Vite hot-reloads on save
4. Repeat step 3 to iterate on the UI

Scaffold output: package.json (React 19, Vite 6), vite.config.js, index.html (with Tailwind CDN), src/main.jsx, src/App.jsx (Tailwind utility classes), src/App.css, .gitignore.

Safety: Output directories must be under $HOME or /tmp. Path traversal (.., absolute paths) is rejected. Non-empty directories require force: true.

Requires: node, npx, jq. Egress: registry.npmjs.org, cdn.jsdelivr.net, cdn.tailwindcss.com.

Codegen HTML Skill

The codegen-html skill scaffolds standalone Preact + HTM applications with zero local dependencies:

forge skills add codegen-html

This registers three tools:

Two scaffold modes:

Key differences from codegen-react: No Node.js required. No build step. No npm install. Just open index.html in a browser. Uses class (not className) since HTM maps directly to DOM attributes.

Safety: Same restrictions as codegen-react — output under $HOME or /tmp, path traversal prevention, force: true for non-empty directories.

Requires: jq. Egress: cdn.tailwindcss.com, esm.sh.

GitHub Skill

The github skill provides a complete git + GitHub workflow through script-backed tools:

forge skills add github

This registers fifteen tools:

Workflow: Clone → explore → edit → status → commit → push → create PR. The skill's system prompt enforces this sequence and prevents raw git commands via cli_execute.

Workflow-completion rule: the skill normally requires driving the full sequence in one session without stopping after exploration. Three exceptions allow pausing:

• Ticket-driven mode — if the task originated from a linear_get_issue call (or any external ticket) and the ticket leaves a material question unanswered, post a linear_add_comment asking the question, then stop and wait. Do not guess on irreversible decisions like API contract shape or data-model changes.
• Code planning — if code_plan_create returns complexity: "high" or non-empty risks, present the plan to the user and confirm before writing code.
• Genuine ambiguity — if you cannot determine what to change even after thorough exploration, stop and ask. Do not invent a change.

Ticket-driven PR conventions: when the work originates from a Linear ticket or GitHub issue:

1. Call github_branch_name_from_ticket first to generate a conventional branch name. Do not invent your own scheme like claude/fix-thing.
2. Pass ticket_id (and ticket_url if available) to github_create_pr — the skill builds the back-link footer automatically.
3. PR title format: <type>(<scope>): <short description> [<ticket-id>]. Examples: feat(billing): add invoice creation endpoint [ENG-123], fix(auth): reject empty refresh tokens [ENG-456], chore(deps): bump go to 1.25.3 [INFRA-7].
4. After github_create_pr returns the PR URL, post a single comment back on the originating ticket using the tracker's skill (e.g. linear_add_comment). Do not post the PR URL into the PR itself.

github_branch_name_from_ticket accepts a prefix (default feat; allow-list feat/fix/chore/docs/refactor), lowercases the ticket ID, slugifies the title (lowercase, non-alnum → -, strip leading/trailing -), and truncates to 60 chars cutting at the last hyphen boundary so no half-word is emitted.

Pagination: List tools (github_list_prs, github_list_stargazers, github_list_forks, github_pr_author_profiles, github_stargazer_profiles) support page (1-based) and per_page (default 30, max 100) parameters. Responses include pagination.has_next_page to indicate more results are available.

PII exemption: Profile-returning tools (github_get_user, github_pr_author_profiles, github_stargazer_profiles) are pre-configured in the default policy scaffold's no_pii allow_tools list, so they can return public profile data (emails, bios) without triggering PII guardrails. See Per-Tool PII Exemptions.

Requires: gh, git, jq. Optional: GH_TOKEN. Egress: api.github.com, github.com.

Code-Agent Skill

The code-agent skill enables autonomous code generation and modification using builtin code-agent tools:

forge skills add code-agent

This registers eight tools:

The skill uses denied tools (file_write, file_edit, file_patch, file_read, schedule_*) to ensure the LLM uses the skill's own tool wrappers instead of raw builtins. All file operations are confined to the agent's working directory via PathValidator.

Requires: bash, jq. Egress: registry.npmjs.org, cdn.tailwindcss.com, pypi.org, files.pythonhosted.org, proxy.golang.org, sum.golang.org, storage.googleapis.com, repo.maven.apache.org, repo1.maven.org.

Linear Skill

The linear skill reads and updates Linear issues through the Linear GraphQL API. It is the entry point for ticket-driven agent workflows — convert ENG-123 into a structured issue payload, transition workflow state, and post progress comments.

forge skills add linear

This registers six tools:

State transition pattern (hard rule): the LLM must call linear_get_workflow_states first to discover a team's state IDs before calling linear_update_issue_state. State names like "Todo" and "In Progress" are not portable across teams.

Commenting etiquette: post at most one comment per agent action — work started, PR opened, work complete. The skill is read/comment/transition only; it does not delete issues, comments, or projects.

Authentication: raw API key in the Authorization header — no Bearer prefix (Linear's API specifically rejects the Bearer form, this is the most common integration bug). guardrails.deny_output redacts any key that leaks back through an error payload.

Workflow integration: typically used as linear_get_issue → code_plan_create → present plan to user → code_agent_* / github_* → linear_add_comment with the PR URL.

Requires: curl, jq. Env: LINEAR_API_KEY (required); LINEAR_DEFAULT_TEAM_ID (optional — accepts a UUID or a team key). Egress: api.linear.app.

Code Plan Skill

The code-plan skill turns a free-form task description plus a repository on disk into a structured implementation plan — files to create, files to modify, tests to add, risks, complexity. Returns JSON only; execution happens in code-agent / github.

forge skills add code-plan

This registers two tools:

Repo signal extraction: code_plan_create automatically samples the repo so the LLM has enough context without the agent pre-reading files:

1. Top 200 entries of git ls-files (or find fallback for non-git dirs)
2. Manifest files: go.mod, package.json, pyproject.toml, setup.py, requirements.txt, Cargo.toml, pom.xml, build.gradle*
3. First 4 KB of README.md if present

Size-bounded at 256 KB by default (override via PLAN_MAX_REPO_SIGNAL_BYTES). If the repo is too large to fit, the tool returns {"status": "repo_too_large", "tree_bytes", "limit_bytes", "suggestion"} rather than truncating silently — pass context_files to scope the plan to relevant files, or call from a subdirectory.

Plan-then-execute discipline: once a plan is generated, present its summary and files_to_modify / files_to_create lists to the user before writing code. Do not proceed if the plan returns complexity: "high" or non-empty risks without acknowledging them. The plan is a contract: subsequent code-writing tool calls should match the file lists. If the plan turns out to be wrong, regenerate it rather than silently drift from it.

Schema validation with retry: after the LLM call, the script validates the response has all 9 required top-level keys (summary, approach, files_to_create, files_to_modify, tests_to_add, risks, complexity, estimated_file_count, open_questions). On failure → one retry with a schema-reminder follow-up. Still failing → {"status": "error", "error": "llm output did not match plan schema", "raw": "..."}.

Provider selection: ANTHROPIC_API_KEY wins if set, else OPENAI_API_KEY (one_of). Defaults: Anthropic claude-sonnet-4-5, OpenAI gpt-4.1. Override via PLAN_MODEL.

Requires: curl, jq, git. Env: ANTHROPIC_API_KEY or OPENAI_API_KEY (one-of); PLAN_MODEL, PLAN_MAX_REPO_SIGNAL_BYTES (optional). Egress: api.anthropic.com, api.openai.com.