forge-skills

name	forge-skills
description	Meta-guide for Forge's per-project pipeline skills: what Forge does with a skill at runtime, and the standard for authoring / customizing / shadowing one correctly and cheaply. Read or invoke this BEFORE writing, rewriting, or tuning a project's skills — especially non-standard projects (MCP-driven build/deploy, docs-only, single-branch, local-only). Triggers on: /forge-skills, how do Forge skills work, customize skills for this project, author a skill, rewrite a skill, what does Forge do with skills.
user_invocable	true
arguments	[skill-name]

Forge Skills — what they are & how to author them

A Forge skill is the instruction set an AI agent runs for one pipeline stage of one project (triage, clarify, plan, code, review, test, fix, release …). This meta-skill explains how Forge executes skills and the standard for writing/customizing them so they run correctly and don't waste tokens. Read it before touching a project's skills.

1. What Forge does with a skill (runtime model)

• Pipeline = a status ladder. Each stage binds to exactly ONE skill (forge_skills_register). A job at that stage loads that one skill body as its instructions — never all skills at once.
• Per job the agent gets: the bound skill body + a shared preamble (status ladder, complexity/priority enums, relation kinds, handoff schema, branchConfig, creds-as-pointer) that Forge injects and prompt-caches + a check-in bundle from forge_step_start. references/*.md load only when the agent reads them (lazy) — so they cost nothing until needed.
• Scope & shadowing (ISS-388): global skills are read-only templates. A project customizes one by creating a same-name project skill, which shadows the global for that project. There is no fork/override — just shadow-by-name. forge_skills_effective dedups by name (one row per name + shadowsGlobal).
• Server-side + explicit sync: skills live in the Forge cloud per project. Edit = forge_skills_update (server) → forge_skills_push (signals devices) → each device pulls and writes .claude/skills/<name>/. Nothing auto-syncs.

2. Decision tree — do you even need to touch a skill?

Need different pipeline behaviour for THIS project?
├─ A value that changes per project (branch, test URL, creds, a domain fact)?
│     → DON'T edit the skill. Put it in forge_config projectFacts / previewDeploy / branchConfig.
├─ The global stage skill is basically right, tweak the policy/heuristics?
│     → SHADOW it: create a same-name project skill (forge_skills_create), edit, register.
├─ A whole new capability/stage this project needs?
│     → New project skill + register it to a stage (or invoke standalone).
└─ It already works (most projects)?
      → Leave the global. Customisation is the exception, not the default.

3. Core authoring rules (NT1 — non-negotiable)

1. Write WHAT, not HOW. Intent altitude: "build & test the affected packages, push only if green." The agent infers the actual commands from the repo (package.json / Makefile / Cargo / lockfile). Bad: hardcode npm run build. Good: "build the affected package (infer the command from the repo)."
2. Don't restate the preamble. Status ladder, enums, "status LAST", handoff schema, decompose protocol, worktree rules are already injected every job. Restating them = drift when they change.
3. Don't hardcode project config. repoPath, base/production branch literals, test URLs, 🔒 credentials → come from the check-in bundle / forge_config / previewDeploy / projectFacts. Never inline a secret (it syncs to disk).
4. Only write non-inferable POLICY the agent can't derive from the repo: gitflow/merge model, deploy gate, stage exits that override the default ladder, domain heuristics, conventions.
5. Token economy — put the right thing in the right place:
   • Inline (always-paid): decision logic the agent must always see — gates, exit rules, "when to X vs Y".
   • references/*.md (lazy): long checklists, templates, playbooks, examples.
   • projectFacts (preamble): per-project values referenced by many skills.
6. Emit structured signals — don't bury machine-consumed data in the comment. When a stage produces data a later stage or an aggregator reads (friction, UX gaps, metrics, learnings), write it to its dedicated tool/table (forge_feedback, forge_ux_findings, …) as a non-blocking side-channel — in addition to the human-facing comment and the status transition, never instead of them. The comment is for the reader; the structured row is for the machine. A failed emit must never change the stage's verdict.
7. Consume a project-wide standard as a gated fact, not hardcoded prose. A standard the pipeline must honor across issues (e.g. a UX contract) lives as an always-inject projectFacts key and is referenced with an "if the project has <fact>" guard, so projects without it are unaffected. Read the standard from the fact; don't bake it into the skill body (that can't be tuned per project and drifts).

4. Failure modes to avoid

1. Hardcoding mechanics (build/test/deploy commands) → breaks when the repo changes; violates rule 1.
2. Restating preamble content → silent drift.
3. Double-merge: the skill git merges AND server mergeStates merges the same branch → empty-commit loop. Pick ONE merge mechanism.
4. Files without encoding: when adding references via MCP, set encoding:"utf8" (or base64) — a missing encoding can break the runner's skill sync.
5. Secrets inline; or putting a per-project value in the body instead of projectFacts.
6. Over-splitting: moving decision logic into a reference the agent may skip. Keep gates inline.

5. Authoring workflow (read → draft → ship → verify)

1. Read what's live: forge_skills_effective (catalog + which are shadowed) and the global body you're customizing. Reconcile first — the server may have diverged from any local copy.
2. Draft from references/authoring-template.md; run it through references/authoring-checklist.md.
3. Ship server-first: forge_skills_update (existing project skill) or forge_skills_create (new shadow). Then forge_skills_register to bind it to a stage if it isn't already.
4. Sync + verify: forge_skills_push → then verify ON DISK (md5/grep the marker in .claude/skills/<name>/SKILL.md). The WS sync-status dashboard is unreliable (false-negatives) — trust the disk.

6. Stage → skill quick reference (default pipeline)

Status (stage)	Skill	Owns
open	forge-triage	completeness gate, complexity/category/priority
confirmed	forge-clarify	reproduce/validate, confidence gate
clarified	forge-plan	implementation plan, decompose decision
approved	forge-code	implement, build/test, simplify, push
developed	forge-review	independent 5-axis review (report-only)
testing	forge-test	QA against the deploy (functional + UX/a11y)
reopen	forge-fix	scoped fix from review/QA feedback + guard test
released	forge-release	merge-to-prod (guarded) + deploy + close
— (meta)	forge-skills · forge-skill-audit · forge-guidebook	author skills · audit pipeline quality · user docs

7. Non-standard project patterns

• MCP-driven build/deploy (e.g. a storefront that publishes {theme}.liquid via a vendor MCP): "build/deploy" is MCP tool calls, not a repo build; the local dir is docs + code backup; git is for versioning/backup only. Write skills so: implement edits the source then publishes via the vendor MCP; test verifies on the live service (preview/theme URL), not localhost; release publishes + snapshots a backup. Keep durable invariants in the skill (backup-before-publish, verify-live, build-on-draft) and defer tool mechanics (tool names, traps) to the live vendor MCP playbook so they auto-track. Check whether a builtin family already fits (e.g. the shop-* Epodsystem skills) and adopt/shadow those rather than bending the git-centric defaults.
• Single-branch (base==production): forge-code merges the feature branch to that branch to deploy for testing; forge-release must skip re-merging (guard: already an ancestor) or it empty-commit-loops.
• Docs-only / decision projects: the deliverable is a committed markdown artifact; build/test is "the doc exists and is substantive", not a compile.
• Local-only (no Coolify/preview): the pipeline ends at developed for human review; test/release are skipped.

Ship reminder

Edit the server first (forge_skills_update/create), reconcile before overwriting, push, then verify on disk — never hand-edit only the device copy and assume it stuck.