holocron/docs/research/ai-coding-factory/ai-coding-factory-skills-index.md

AI Coding Factory — Skills Index

Purpose: Temporary build reference. Specifies the trigger description and key constraints for every skill in the library. Use this as the direct input when writing each skill's SKILL.md description field and constraints section. Delete once the actual skill files exist in the repo.

Status: Pre-implementation reference — not a permanent artifact. Source: Derived from ai-coding-factory-design.md (v1.2, May 2026), superseded by ai-coding-factory-principles.md. Security-review skill updated in Session 3 to reflect AST10 Incubator status and correct AST01 scope. Total skills: 34 across 9 categories (7 factory meta-skills added; design/write-spec replaced by factory/write-issue-spec).

---

Role Skills

Skill	Trigger description	Primary output
roles/architect	Architecture review, system design decisions, data model design, ADR creation	Design doc, API contracts, tradeoff analysis
roles/developer	Feature implementation, coding tasks, writing production code against a spec	Working code with tests following project conventions
roles/reviewer	Code review, diff review, reviewing changes before commit or PR	Severity-rated findings, auto-fixed style issues
roles/security	Security audit, OWASP review, STRIDE threat modelling, pre-merge security check	Security findings with remediation guidance
roles/qa	QA, testing a feature end-to-end, finding edge cases in an implementation	Test results, regression tests
roles/ops	Deployment tasks, infrastructure review, CI/CD configuration, runbook creation	Pipelines, manifests, runbooks, deployment plans

---

Design Phase Skills

Skill	Trigger description	Key constraints
design/grill-me	Grill me on this idea, help me think through X before building, interrogate my plan	Must refuse to proceed until all decisions are explicit and all branches of the decision tree are resolved. Never code until the interview is complete. Output: structured decision summary.
design/architecture-review	Review architecture, assess system design, evaluate technical approach	Must present ≥2 options with tradeoffs; never recommend a single option without alternatives
design/break-into-issues	Break this into issues, decompose this spec into tasks, what issues do I need for this	Outputs independently shippable Gitea issue bodies (each can be implemented without the others); embeds full context in each issue (BMAD Scrum Master pattern); does not post issues — outputs ready-to-post bodies for human review

---

Factory Skills (Meta-skills — the factory builds itself)

Skill	Trigger description	Key constraints
factory/write-issue-spec	Write a spec for this issue, draft the issue description for X, create a Gitea issue spec	Produces a complete Gitea issue body: Why (proposal + out-of-scope), Requirements (EARS format; delta-tagged for brownfield: ADDED/MODIFIED/REMOVED), Design notes, Tasks (independently completable checklist). Scale-adaptive: skips design notes for bug fixes; adds architecture section for complex features. Does not post the issue — outputs body for human review.
factory/write-skill	Write a new skill for X, create a SKILL.md that does Y	Produces a complete SKILL.md following the authoring standard (frontmatter, role, when/when-not, required inputs, constraints, process, output format, failure handling). Validates trigger description against three test queries before completing. Flags if the skill overlaps with an existing skill in the library.
factory/write-workflow	Write a workflow for X, chain these skills into a workflow, create a workflow document	Produces a .agents/workflows/<name>.md with: skill sequence, WorkflowContext schema (what each skill receives and returns), HITL gates marked before every irreversible action, failure paths documented.
factory/write-adr	Write an ADR, document this architectural decision, record this decision	Produces docs/adr/NNN-title.md in standard format: title, date, status (Proposed/Accepted/Superseded), context, decision, consequences, alternatives considered. Increments ADR number from existing files. Never edits an existing Accepted ADR — creates a new one that supersedes it.
factory/write-eval	Write evals for this skill, create eval.yaml for X, add tests for this skill	Produces .agents/evals/<category>/<skill>/eval.yaml with: ≥1 explicit trigger test, ≥1 implicit trigger test, ≥1 negative trigger test (adjacent task that must NOT activate), ≥2 output tests (deterministic: schema/contains/regex), ≥1 LLM-rubric quality test.
factory/upgrade-skill	This skill is wrong, fix this skill, update skill X, skill X is behaving incorrectly	Updates SKILL.md body, bumps version in frontmatter, adds a new eval test case that captures the correction (so the same failure cannot recur silently). Never reduces the existing eval suite — only adds to it.
factory/validate-skill	Check this skill, does this skill meet the standard, review this SKILL.md, audit skill X	Validates against: frontmatter completeness, trigger description quality (three-test check), constraints section presence, failure handling section, co-located eval exists. Outputs severity-rated findings: missing eval = critical; missing failure handling = high; weak trigger description = high.

---

Implementation Phase Skills

Skill	Trigger description	Key constraints
implement/implement-feature	Implement a feature, build this, write the code for X	Must start from a linked Gitea issue with an EARS spec; flags if none exists; no unrequested abstractions; updates docs/spec/ as part of implementation if behaviour changes
implement/refactor	Refactor this code, improve structure, clean up	Preserves all existing behaviour; documents what changed and why
implement/write-docs	Write documentation, add docstrings, generate README	Derives from code and spec; does not invent behaviour

---

Test Phase Skills

Skill	Trigger description	Key constraints
test/write-tests	Write tests, generate test cases, add unit tests	Derives from spec NOT implementation; pytest for Python, Vitest/Jest for TypeScript
test/generate-test-data	Generate test data, create fixtures, sample data	Structurally valid, semantically unusual; flags PII risk
test/review-test-coverage	Review test coverage, find untested paths, coverage gaps	Reports against spec acceptance criteria

---

Review Phase Skills

Skill	Trigger description	Key constraints
review/code-review	Review this code, check this diff, pre-commit review	Severity-rated: critical/high/low; auto-fixes obvious style issues; flags architectural concerns
review/security-review	Security review, OWASP check, pre-merge security scan	OWASP LLM Top 10 + Agentic AI Top 10 for application code; OWASP Agentic Skills Top 10 (AST10, Incubator draft) if reviewing third-party skills — for self-authored factory skills use AST03/04/06/07/09 categories, not AST01 (which requires attacker-controlled content); includes credential and licence checks
review/pr-description	Write PR description, describe this change	Derives from diff; includes what changed, why, and what to review carefully
review/changelog-entry	Write changelog entry, add to CHANGELOG, release notes	Conventional changelog format; derives from PR description and diff

---

Deploy Phase Skills

Skill	Trigger description	Key constraints
deploy/write-ci-pipeline	Write CI pipeline, create Gitea Actions workflow	Gitea Actions YAML; includes secret scan, dependency scan, licence scan, test, build by default
deploy/write-deployment-config	Write deployment config, Docker Compose, K8s manifest	Pinned versions; resource limits on all K8s resources; no hardcoded secrets
deploy/write-ai-review-workflow	Create AI review workflow, automated PR review	Calls AI API via script; posts via Gitea API; never auto-merges
deploy/deployment-checklist	Pre-deployment checklist, ready to deploy, deployment validation	Checks: linked Gitea issue exists and is closed or in-progress, secrets scan, dependency scan, licence scan, tests passing, rollback plan, docs/spec/ updated if behaviour changed; also checks review readiness — which roles (Architect, Reviewer, Security) have been invoked on this change

---

Operate Phase Skills

Skill	Trigger description	Key constraints
operate/write-runbook	Write runbook, operational guide, on-call playbook	Covers: common failure modes, detection, remediation steps, escalation
operate/incident-diagnosis	Diagnose this incident, analyse these logs, root cause analysis	Produces structured finding with confidence levels; never recommends production remediation directly
operate/post-mortem	Write post-mortem, incident review, after-action report	Blameless format; covers timeline, root cause, governance change
operate/inspect-deployment	Check deployment health, container status, what's running	Read-only; uses Docker MCP and/or K8s MCP; summarises health

---

IaC Domain Skills

Skill	Trigger description	Key constraints
iac/write-ansible-role	Write an Ansible role, create Ansible automation, Ansible role for X	Idempotency review must specifically check: missing creates: on file-creating tasks, unconditional handlers (should use notify), absent rollback strategies, shell/command tasks without guards. Molecule test scaffold included; version pinned in frontmatter
iac/write-terraform-module	Write Terraform module, Terraform config for X	Pin provider versions; never use Terraform provisioners to call Ansible — HashiCorp designates provisioners a "last resort" and they break idempotency; use a separate CI/CD Ansible stage instead; includes variables, outputs, validation blocks
iac/write-k8s-manifest	Write Kubernetes manifest, K8s deployment for X	Resource limits required; security context required; network policy required
iac/write-docker-compose	Write Docker Compose, compose stack for X	Pinned image versions; secrets via env vars; healthchecks included
iac/proxmox-vm-spec	Create Proxmox VM, Proxmox config for X	Loads references/proxmox-cluster.md; bpg/proxmox provider; version pinned
iac/iac-security-review	Security review this IaC, check Terraform/Ansible for issues	Checks: hardcoded secrets, overly permissive access, missing limits, unpinned versions, Terraform provisioners, non-idempotent Ansible patterns (shell/command without guards, missing creates:, unconditional handlers)
iac/write-molecule-test	Write Molecule tests, Ansible testing, role test	Generates converge.yml, verify.yml, molecule.yml

---

Gitea Integration Skills

Skill	Trigger description	Key constraints
gitea/setup-gitea-mcp	Set up Gitea MCP, connect agent to Gitea, configure MCP	Generates config + dedicated agent user setup; includes --tools filter recommendations
gitea/post-pr-review	Post review findings to PR, add review comments, submit review	Uses Gitea MCP; tiered severity; never auto-merges
gitea/create-issue	Create a Gitea issue, log this as a bug, file an issue	Uses Gitea MCP; requires structured finding as input

---

Cross-Cutting Skills

Skill	Trigger description	Key constraints
cross-cutting/session-handoff	Session handoff, save context, pausing work	Captures: current state, next steps, decisions with rationale, linked Gitea issue number; prompts LESSONS.md extraction; does NOT manage spec files — docs/spec/ is updated in-PR, not at handoff
cross-cutting/governance-check	Check this against governance rules, is this allowed	Validates proposed action against AGENTS.md
cross-cutting/git-commit-message	Write commit message, conventional commit, git message	Conventional commits format; derives from diff

---

Extracted and updated from ai-coding-factory-design.md v1.2 and ai-coding-factory-implementation-guidance.md v1.2, May 2026. Delete this file once all skills exist as actual SKILL.md files in the repo. The factory/ skills category is new in v1.2 — these meta-skills are Phase 2 priority 1.