Skip to content
Back to search

aiwerk-skills

MarketplaceWorks with Claude CodeGitHub

AI Werk Skills: open Agent Skills for intake, orchestration, eval and governance, release and operations.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/anpod--ai-software-factory/badge.svg)](/listings/anpod--ai-software-factory)

HTML

<a href="/listings/anpod--ai-software-factory"><img src="/api/listings/anpod--ai-software-factory/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/AnPod/ai-software-factory.git ~/aiwerk-skills
cd your-project
~/aiwerk-skills/install.sh            # dry run: shows what it would link
~/aiwerk-skills/install.sh --apply    # links the skills into .claude/skills and .agents/skills

Then, in your coding agent:

> Use the aiwerk-init skill to set up the software factory for this project.

Other harnesses: `--harness copilot,opencode,cursor,gemini,droid` or `--harness all`. Install for every project with `--scope user`. Remove with `--uninstall --apply`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 25 lines
  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "aiwerk-skills",
  4. "description": "AI Werk Skills: open Agent Skills for intake, orchestration, eval and governance, release and operations.",
  5. "owner": {
  6. "name": "AI WERK d.o.o.",
  7. "url": "https://aiwerk.si"
  8. },
  9. "plugins": [
  10. {
  11. "name": "aiwerk-skills",
  12. "description": "All 23 AI Werk Skills (setup, stages 01 to 05 and meta) with the Markdown project brain.",
  13. "version": "0.5.1",
  14. "author": {
  15. "name": "AI WERK d.o.o.",
  16. "url": "https://aiwerk.si"
  17. },
  18. "source": "./",
  19. "category": "development",
  20. "homepage": "https://github.com/AnPod/ai-software-factory",
  21. "repository": "https://github.com/AnPod/ai-software-factory",
  22. "license": "Apache-2.0"
  23. }
  24. ]
  25. }
README.md · README · 239 lines
  1. # AI Werk Skills
  2. **Set up a software factory inside the coding agent you already use.**
  3. [![CI](https://github.com/AnPod/ai-software-factory/actions/workflows/ci.yml/badge.svg)](https://github.com/AnPod/ai-software-factory/actions/workflows/ci.yml)
  4. [![SkillSpector scan](https://github.com/AnPod/ai-software-factory/actions/workflows/skillspector.yml/badge.svg)](https://github.com/AnPod/ai-software-factory/actions/workflows/skillspector.yml)
  5. [![Agent evals](https://github.com/AnPod/ai-software-factory/actions/workflows/evals.yml/badge.svg)](https://github.com/AnPod/ai-software-factory/actions/workflows/evals.yml)
  6. [![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
  7. [![Agent Skills standard](https://img.shields.io/badge/format-Agent%20Skills-black.svg)](https://agentskills.io)
  8. AI Werk Skills is a set of plain-Markdown [Agent Skills](https://agentskills.io) that turn Claude Code, GitHub Copilot CLI, Codex, OpenCode, Pi, Cursor, Gemini CLI or Factory Droid into a repeatable software delivery line. The skills interview your team, map which tools your agents can reach, ask before they touch anything, and keep a timestamped project memory (the *brain*) that every later step reads first.
  9. No server, no database, no account. Clone it, link the skills, ask your agent to run `aiwerk-init`.
  10. ## Quick start
  11. ```bash
  12. git clone https://github.com/AnPod/ai-software-factory.git ~/aiwerk-skills
  13. cd your-project
  14. ~/aiwerk-skills/install.sh # dry run: shows what it would link
  15. ~/aiwerk-skills/install.sh --apply # links the skills into .claude/skills and .agents/skills
  16. ```
  17. Then, in your coding agent:
  18. > Use the aiwerk-init skill to set up the software factory for this project.
  19. Other harnesses: `--harness copilot,opencode,cursor,gemini,droid` or `--harness all`. Install for every project with `--scope user`. Remove with `--uninstall --apply`.
  20. ## How it works
  21. ```mermaid
  22. flowchart LR
  23. subgraph Setup ["One-time setup"]
  24. direction TB
  25. S0["install.sh --apply"] --> S1["aiwerk-init\nrules and brain"]
  26. S1 --> S2["aiwerk-landscape\ntools and consent"]
  27. S2 --> S3["aiwerk-survey\nfirst full read"]
  28. end
  29. subgraph Line ["Day-to-day delivery line"]
  30. direction LR
  31. D1["01 Intake and context\nreadiness, intake,\nspec, context"]
  32. D2["02 Orchestration\nplan, dispatch,\nsandbox"]
  33. D3["03 Eval and governance\nreview, test-gate,\nsecurity-gate, policy"]
  34. D4["04 Release\nrelease, deploy-check,\ndocs-sync"]
  35. D5["05 Operations\nincident, slo,\nincident-to-spec"]
  36. D1 --> D2 --> D3 --> D4 --> D5
  37. D5 -- "resolved bug becomes new spec" --> D1
  38. end
  39. Brain[(".aiwerk/brain/\nshared dated notes\nkept fresh by aiwerk-refresh")]
  40. Meta["Meta\naiwerk-health and aiwerk-skill-audit"]
  41. Setup --> D1
  42. Setup -. "writes" .-> Brain
  43. Line <--> Brain
  44. Meta -. "checks" .-> Brain
  45. ```
  46. 1. **`aiwerk-init`** asks which harnesses you use, where work comes in (Slack, Jira, Confluence, Linear, GitHub), what may trigger an agent, which stages to switch on and how autonomous agents may be.
  47. 2. **`aiwerk-landscape`** finds the MCP servers, CLIs, plugins and browser tools your agents can reach, places them on the delivery stages and asks for your consent per source.
  48. 3. **`aiwerk-survey`** reads the project into the brain: stack, commands, architecture, owners, conventions and gaps, each with sources.
  49. 4. **Stage skills** (see below) take work from intake to operations. Each reads the brain first and writes what it learns back.
  50. ### The brain
  51. `.aiwerk/brain/` is a folder of Markdown pages, versioned with your code, readable by people and agents. Every page records when it was gathered, by which skill, from which sources and how long it stays valid:
  52. ```yaml
  53. ---
  54. title: Payments service
  55. kind: project/service
  56. gathered_at: 2026-11-19T10:42:00Z
  57. gathered_by: aiwerk-survey
  58. sources:
  59. - git:main@27c54c6
  60. - mcp:atlassian/confluence:PAY
  61. ttl_days: 14
  62. confidence: medium
  63. ---
  64. ```
  65. The brain never updates itself silently in the background. It stays current in four ways:
  66. - **During normal work:** Every skill reads the brain first, writes what it learns back, updates `index.md` and appends a line to `log.md`.
  67. - **After a merge:** `aiwerk-docs-sync` checks the git diff, updates brain pages made stale by the change and marks unchanged ones as verified.
  68. - **When pages expire:** If a skill needs a page older than its `ttl_days`, it tells you its age and asks whether to refresh it or use it as is. `aiwerk-refresh` checks the whole brain at once and re-gathers only the pages you approve.
  69. - **By hand:** Pages are plain Markdown in your repository, so you can edit them directly. Anything under a `## Human notes` heading is off-limits to skills and will never be overwritten.
  70. The idea follows Andrej Karpathy's LLM Wiki pattern: a maintained knowledge base instead of re-discovering the project on every task.
  71. ## Skills
  72. The stages follow a five-station delivery line. All 23 skills across setup, stages 01 to 05 and meta are available.
  73. | Skill | Stage | What it does | Status |
  74. |---|---|---|---|
  75. | `aiwerk-init` | Setup | Interview, factory settings, creates the brain | available |
  76. | `aiwerk-landscape` | Setup | Maps MCP servers, CLIs and plugins to stages, asks consent per source | available |
  77. | `aiwerk-survey` | 01 Intake and context | First full read of the project into the brain | available |
  78. | `aiwerk-refresh` | Setup | Finds stale or broken knowledge and renews it with your approval | available |
  79. | `aiwerk-readiness` | 01 Intake and context | Scores how ready the repository is for agents | available |
  80. | `aiwerk-intake` | 01 Intake and context | Turns a Jira, Linear, Slack or GitHub item into a ticket | available |
  81. | `aiwerk-spec` | 01 Intake and context | Writes a spec with acceptance criteria grounded in the brain | available |
  82. | `aiwerk-context` | 01 Intake and context | Assembles the minimal context one task needs | available |
  83. | `aiwerk-plan` | 02 Orchestration | Splits a spec into independent tasks | available |
  84. | `aiwerk-dispatch` | 02 Orchestration | Runs tasks headless in the chosen harness | available |
  85. | `aiwerk-sandbox` | 02 Orchestration | Runs a task in a worktree, container or sandbox service | available |
  86. | `aiwerk-review` | 03 Eval and governance | Adversarial review of a diff against its spec | available |
  87. | `aiwerk-test-gate` | 03 Eval and governance | Runs and extends tests, blocks regressions | available |
  88. | `aiwerk-security-gate` | 03 Eval and governance | Runs the scanners you have (Snyk, Semgrep, GitGuardian, Socket, Wiz) | available |
  89. | `aiwerk-policy` | 03 Eval and governance | Checks PII, licence and data rules from the brain | available |
  90. | `aiwerk-release` | 04 Release | Release notes, version, PR description | available |
  91. | `aiwerk-deploy-check` | 04 Release | Pre-deploy checklist with rollback trigger | available |
  92. | `aiwerk-docs-sync` | 04 Release | Updates docs and brain after a merge | available |
  93. | `aiwerk-incident` | 05 Operations | Triage from Datadog, Sentry, PagerDuty, Grafana | available |
  94. | `aiwerk-incident-to-spec` | 05 Operations | Turns a resolved incident into a new spec | available |
  95. | `aiwerk-slo` | 05 Operations | Summarises SLOs and error budgets | available |
  96. | `aiwerk-health` | Meta | Stage rollout, brain freshness, connector coverage | available |
  97. | `aiwerk-skill-audit` | Meta | Scans every installed skill with SkillSpector | available |
  98. ## Examples
  99. Every project starts the same way once: run `install.sh --apply`, then ask your agent to run `aiwerk-init`, `aiwerk-landscape` and `aiwerk-survey`. After that, trigger only the skills you need.
  100. ### iOS app
  101. You are building a Swift app and want to add Face ID login without breaking existing screens or leaking user data.
  102. - **Start the feature:** Point the agent at a GitHub issue and run `aiwerk-intake`, then `aiwerk-spec`. It checks the brain for your Swift version, navigation setup and auth rules, then writes a clear spec.
  103. - **Build it:** Run `aiwerk-plan` to split the work into small tasks (UI, Keychain helper, tests). Run `aiwerk-sandbox` so the agent works in a separate git worktree while you stay on your main branch.
  104. - **Check before merging:** Run `aiwerk-test-gate` (Xcode tests), `aiwerk-review` (checks the diff against the spec) and `aiwerk-policy` (checks that no personal user data gets logged).
  105. - **Ship it:** Run `aiwerk-release` to draft TestFlight or App Store release notes and the PR summary.
  106. ### Web app
  107. You have a frontend and API web app (React, Next.js, etc.) and a customer reports a broken checkout button in Slack.
  108. - **Turn the message into work:** Paste the Slack thread and run `aiwerk-intake`, `aiwerk-spec` and `aiwerk-context` (pulls only the checkout files the agent needs).
  109. - **Fix and verify:** Let the agent make the fix, then run `aiwerk-test-gate` (unit and browser tests) and `aiwerk-security-gate` (checks for bad packages or unsafe code).
  110. - **Wrap up after merge:** Run `aiwerk-docs-sync` so the brain and project docs stay in sync with the change.
  111. ### Backend, SaaS and microservices
  112. You run several backend services (payments, auth, billing) with Datadog, Sentry, Jira and strict data rules.
  113. - **When something breaks at 2 AM:** Run `aiwerk-incident`. It reads the brain to see who owns the service and how it is wired, then checks the monitoring tools you allowed (Datadog, Sentry, Grafana, PagerDuty) to narrow down the cause.
  114. - **Prevent a repeat:** Once fixed, run `aiwerk-incident-to-spec` to turn what happened into a spec for a permanent fix.
  115. - **Roll out safely:** Use `aiwerk-plan` and `aiwerk-dispatch` to run tasks headless across changes, `aiwerk-policy` and `aiwerk-security-gate` to enforce compliance, and `aiwerk-deploy-check` before pushing to production so you have a clear rollback trigger.
  116. - **Weekly checkup:** Run `aiwerk-slo` to summarise uptime and error budgets and `aiwerk-refresh` to renew stale pages in the brain.
  117. ### Raspberry Pi and hardware projects
  118. You are building a home sensor or robot script in Python or C++ on a Raspberry Pi, and you only work on it on weekends.
  119. - **Pick up where you left off:** Because `.aiwerk/brain/` records your GPIO pin layout, OS version and deploy command, you do not have to re-explain your setup each time. Run `aiwerk-refresh` when you swap a sensor or update the Pi.
  120. - **Add a new sensor:** Run `aiwerk-spec` and `aiwerk-plan` to map out the driver code and pin wiring before editing anything.
  121. - **Test safely:** Run `aiwerk-review` and `aiwerk-test-gate` (with mocked hardware tests on your laptop) before copying code to the Pi.
  122. - **Deploy cleanly:** Run `aiwerk-deploy-check` to double-check systemd service restarts and a quick rollback path if the Pi hangs.
  123. ## Harness support
  124. | Harness | Skill folder | Headless run |
  125. |---|---|---|
  126. | Claude Code | `.claude/skills` | `claude -p` |
  127. | GitHub Copilot CLI | `.agents/skills` (also reads `.github/skills` and `.claude/skills`) | `copilot -p` |
  128. | OpenAI Codex | `.agents/skills` | `codex exec` |
  129. | OpenCode | `.opencode/skills` (also reads `.claude` and `.agents`) | `opencode run` |
  130. | Pi | `.agents/skills` | `pi -p` |
  131. | Cursor CLI | `.cursor/skills` | `cursor-agent -p` |
  132. | Gemini CLI | `.gemini/skills` | `gemini -p` |
  133. | Factory Droid | `.factory/skills` | `droid exec` |
  134. GitHub Copilot CLI runs the agent evals in CI. Claude Code uses the same eval harness, but this repository's CI has no Anthropic key yet, so Claude Code evals run locally (see [Tests](#tests)). The others read the same `SKILL.md` format; reports from users are welcome.
  135. ### Installing per harness
  136. - **Claude Code (plugin marketplace):** add this repository as a marketplace and install the plugin directly from Claude Code:
  137. ```text
  138. /plugin marketplace add AnPod/ai-software-factory
  139. /plugin install aiwerk-skills@aiwerk-skills
  140. ```
  141. Or install from a local clone with `~/aiwerk-skills/install.sh --harness claude --apply`.
  142. - **GitHub Copilot CLI:** run `~/aiwerk-skills/install.sh --harness copilot --apply` in your repository (links into `.agents/skills`; Copilot CLI also reads `.github/skills` and `.claude/skills`). Add `--scope user` to install for every project.
  143. - **OpenAI Codex:** run `~/aiwerk-skills/install.sh --harness codex --apply` (links into `.agents/skills`, or `~/.agents/skills` with `--scope user`).
  144. - **OpenCode:** run `~/aiwerk-skills/install.sh --harness opencode --apply` (links into `.opencode/skills`, or `${XDG_CONFIG_HOME:-$HOME/.config}/opencode/skills` with `--scope user`; OpenCode also reads `.claude/skills` and `.agents/skills`).
  145. ### Headless CI recipes
  146. See [recipes/github-actions/](recipes/github-actions/README.md) for two copy-and-paste GitHub Actions workflows that run AI Werk Skills headless with `copilot -p` or `claude -p` using narrow tool allowlists:
  147. - [issue-intake-and-spec.yml](recipes/github-actions/issue-intake-and-spec.yml): turns an issue labelled `aiwerk:spec` into a brain ticket and spec.
  148. - [pr-governance-gates.yml](recipes/github-actions/pr-governance-gates.yml): runs stage 03 review, test, security and policy gates on same-repository pull requests.
  149. ## Safety
  150. Skills run with your agent's permissions, so they deserve the same scrutiny as code. What this repository does about it:
  151. - **Scanned.** Every pull request, every push to `main` and every release is scanned with [NVIDIA SkillSpector](https://github.com/NVIDIA/skillspector), static analysis for prompt injection, data exfiltration, credential access and other risky patterns. The report is attached to every run and release, and non-PR runs upload findings to **Security > Code scanning**. A clean scan lowers risk; it does not prove a skill is safe, so read what you install.
  152. - **Readable.** Skills are Markdown. The only script inside the skills is a read-only Python checker (`aiwerk-refresh/scripts/brain_status.py`): standard library, no network, writes nothing.
  153. - **Asks first.** Skills never install, connect or authenticate tools. `aiwerk-landscape` records your consent per source, and other skills only use what you allowed.
  154. - **No secrets in the brain.** Skills record where knowledge came from, never tokens or keys. `brain_status.py` flags anything that looks like a credential, does not follow symbolic links, and never prints the match.
  155. - **Contained installer.** `install.sh` is a dry run unless you pass `--apply`, makes no network calls, only creates links or copies in skill folders, never overwrites a folder it did not create, and refuses to write through a symbolic link inside the project.
  156. - **Untrusted text stays data.** Every skill treats brain pages, repository files, tickets and tool output as data, never as instructions, and runs project commands only when the project's own files define them.
  157. - **Locked-down CI.** Workflows default to read-only tokens (with narrow write permissions only in separate post-scan jobs for SARIF upload and release assets), keep no git credentials, and pin every action to a commit. `main` accepts changes only through pull requests with passing checks.
  158. Found a problem? See [SECURITY.md](SECURITY.md).
  159. ## Tests
  160. Three layers, all in GitHub Actions:
  161. | Workflow | What it checks | When |
  162. |---|---|---|
  163. | **CI** | Skill format (name, description, links, risky shell patterns, the untrusted-data rule), brain template, unit tests for the checker and the eval runner, installer end to end on Linux and macOS, ShellCheck | every push and PR |
  164. | **SkillSpector scan** | Static security scan of all skills, JSON and Markdown reports, SARIF in code scanning | every push and PR, weekly, every release |
  165. | **Agent evals** | Runs GitHub Copilot CLI (and Claude Code when an Anthropic key is set) with the skills on a sample project and checks what they wrote: required pages, valid frontmatter, nothing written outside `.aiwerk/`, no secrets copied from MCP config, report-only mode changes nothing | weekly, on demand, and on pushes to `main` or PRs that change skills or evals |
  166. Run locally:
  167. ```bash
  168. python3 scripts/validate_skills.py
  169. python3 -m unittest discover -s tests -v
  170. bash tests/test_install.sh
  171. COPILOT_GITHUB_TOKEN=... python3 evals/run_evals.py --harness copilot # needs the copilot CLI
  172. ANTHROPIC_API_KEY=... python3 evals/run_evals.py --harness claude # needs the claude CLI
  173. ```
  174. ## Contributing
  175. Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for how skills are written and tested.
  176. ## About
  177. AI Werk Skills is maintained by [AI WERK](https://aiwerk.si), a software engineering consultancy in Ljubljana that builds governed software factories for engineering teams. These skills are the open, single-repository version of that work. Teams that want it across many repositories, with their own integrations, hardened access and a shared brain, sometimes ask us to set it up with them.
  178. Licensed under the [Apache License 2.0](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.