git clone --depth 1 https://github.com/jeremylongshore/tons-of-skills-marketplace /tmp/agency-os && cp -r /tmp/agency-os/plugins/ai-agency/agency-os/skills/agency-os ~/.claude/skills/agency-osSKILL.md
# agency-os
Notion-as-source-of-truth dispatch board. One Tasks database, one Hub page, one
page per Corpus, one page each for General Guidance and Resources. The skill
mutates Notion via the Notion MCP (`mcp__*__notion-*` tools); only
`references/notion-pointers.json` is committed to git.
**Skill name decision:** the skill is named `agency-os` (matching the repo). All
commands are `/agency-os <cmd>`. This is the single plugin entry point; there
is no `agency-os/notion` sub-namespace. If you embed this plugin alongside
others, prefix commands with `agency-os` to avoid collisions.
## Overview
agency-os turns a single Notion database into a multi-status dispatch board for
AI work. The model is intentionally narrow:
- **One Tasks database** is the source of truth for status, priority, model
selection, and ownership. No parallel kanban tools.
- **One Hub page** holds the General Guidance, Resources, and Corpus pointers
that every task consults.
- **Tasks flow through five statuses**: Suggestion → Discussion → To-Do →
In Progress → Done. The dedup gate at each transition prevents accidental
re-execution.
- **`run`** fans approved To-Do rows out to parallel agents. Each task carries
its own model selection (Haiku for cheap fan-out, Sonnet for default,
Opus for hard reasoning) and respects declared dependencies.
The skill is **stateless on disk** — the only committed artifact is
`references/notion-pointers.json` (database/page IDs). All runtime state lives
in Notion.
For the full architecture (status flow, sync protocol, workspace structure,
pointer/cache format), see [`references/architecture.md`](references/architecture.md).
## Prerequisites
- **Notion MCP server installed**:
`npx -y @notionhq/notion-mcp-server` (declare in `.mcp.json`)
- **Notion integration token** (`NOTION_TOKEN`) with read+write access to your
workspace. Add `.env` to `.gitignore` — never commit the token.
- **A Notion Tasks database** with the columns the skill expects (see
`references/architecture.md` § "Workspace structure" for the schema). The
`/agency-os init` command can scaffold this for you.
- **Python 3** for the optional `scripts/query-tasks.py` helper.
First-time setup:
```bash
ccpi install agency-os
# then in Claude Code:
/agency-os init --harness=basic --haiku=cost-tier --sonnet=default --opus=hard-reasoning
```
## Instructions
The skill is a CLI surface over Notion. Three usage patterns:
1. **Direct command invocation** — `/agency-os <cmd> [args]`. See
[`references/commands.md`](references/commands.md) for the full reference
of 19 commands (`init`, `scaffold`, `suggest`, `discuss`, `log`,
`add-subtask`, `approve`, `start`, `refresh`, `run`, `done`, `kill`,
`next`, `status`, `list`, `show`, `update`, `move`, plus `launch` alias).
2. **Natural-language driving** — the skill translates conversational chat into
the corresponding command. Examples in
[`references/natural-language.md`](references/natural-language.md).
3. **Batch execution** — `/agency-os run [--go]` fans the entire To-Do queue
out to parallel agents with per-task model selection. See `## Examples`
below for the canonical flow.
Status flow is enforced — you cannot skip a stage. Every command performs a
sync preflight to ensure your local view of Notion is current (see
`references/architecture.md` § "Sync — preflight on every command").
When drafting any user-facing copy (READMEs, blog posts, launch surfaces),
apply the positioning brief at
[`references/positioning.md`](references/positioning.md) before writing.
## Output
Every command returns to chat with:
- **Verdict line** — `✅ <action>` or `⚠️ <reason>` (one line, scannable)
- **Affected task IDs and titles** — every task touched, with its new status
- **Next-action hint** — what command the operator would typically run next
Batch `run` additionally emits:
- A per-task pass/fail table
- Total model spend estimate (Haiku/Sonnet/Opus call counts)
- Outstanding-dependency callouts for tasks that couldn't start
## Error Handling
The skill fails closed on five well-defined cases (full details in
`references/architecture.md` § "Status flow — the dedup gate"):
| Condition | Behavior |
|---|---|
| Notion API auth fails | Halt, print "NOTION_TOKEN missing or invalid", exit 1 |
| Database/page ID drift (pointers stale) | Halt, print "Run `/agency-os refresh`", exit 1 |
| Status-flow violation (e.g. `approve` on a Suggestion) | Halt with the required prerequisite step quoted |
| Dependency cycle detected during `run` | Halt, list the cycle, exit 1 |
| Task missing required model selection | Halt, print "Run `/agency-os update <id> --model <tier>`" |
The skill never silently corrects state in Notion — every fix is an explicit
command the operator must run.
## Examples
Capture a chat insight as a Suggestion:
```text
User: add a suggestion: refactor the auth flow to use the new token cache
Skill: → /agency-os suggest "refactor the auth flow to use the new token cache"
✅ Created Suggestion #t-2026-05-23-001 in corpus "platform"
Next: /agency-os discuss t-2026-05-23-001
```
Approve and run a batch:
```text
User: approve t-2026-05-23-{001..003} then run the queue
Skill: ✅ Approved 3 tasks → To-Do
/agency-os run --go
→ fanning to 3 parallel agents...
✅ Done: 2 | ⚠️ Blocked on deps: 1 | Total spend: ~$0.04
```
More examples and the full command catalog are in
[`references/commands.md`](references/commands.md).
## Resources
- **Plugin source**: <https://github.com/ratamaha-git/agency-os>
- **Launch post**: <https://automatelab.tech/agency-os-launch/>
- **`references/architecture.md`** — status flow, sync protocol, workspace schema
- **`references/commands.md`** — full CLI reference (19 commands)
- **`references/natural-language.md`** — chat-to-command translation table
- **`references/positioning.md`** — canonical brief for user-facing copy
- **`references/general-guidance.md`** — shared operating prinGuard the beads execution record: enforce the write-flush-verify discipline that defeats the bd rapid-write race, audit epic dependency graphs for cycles and orphans, catch closures whose title overstates what shipped, flag open beads carrying no disposition or a disproven premise, and reconcile bd against its GitHub and Plane projections. Owns RECORD INTEGRITY; delegates graph analysis to bead-dependency-mapper and epic-closure drift to bead-epic-auditor rather than duplicating them. Use before closing an epic, after any batch of bd writes, when a bead premise looks stale, or when auditing whether the record matches reality. Trigger with "audit beads", "check the bead DAG", "did that close actually land", "bead hygiene".
Verify every factual assertion in a diff, PR body, commit message, bead note, or governing doc against the actual repository, and fail anything that cannot be substantiated by a command. Use before merging any PR that makes claims about counts, coverage, consumers, enforcement, provenance, or certification, and when auditing standing docs for rot. Trigger with "verify claims", "check this PR body", "is this claim true", "claim audit".
Design and build Omarchy (Quickshell/QML) bar-widget, panel, and service plugins that actually work on a stock install. Knows the hard runtime constraint (no node on the graphical session PATH), the first-party contracts (BarWidget, Panel, KeyboardPanel, PanelKeyCatcher, Service), the curl-from-QML data pattern, FileView persistence, and the marketplace submission bar. Use when starting a new Omarchy plugin, porting a plugin off an external runtime, wiring a service to a bar widget, or deciding how a widget should fetch and persist. Trigger with "build an omarchy plugin", "omarchy widget", "quickshell plugin", "port this plugin to QML".
Audit an Omarchy plugin before it reaches the marketplace: prove it installs and runs on a stock box (no node/python on the session PATH), run the omarchy-submit gate lane, validate on the rig with omarchy-plugin-validate and qmllint, and check the QML security invariants and first-party idiom contracts. Read-only: it reports and blocks, it does not rewrite the plugin. Use before submitting an entry, after any data-layer change, or when a plugin works on the dev box and you need to know whether it works for a real user. Trigger with "audit this omarchy plugin", "is this plugin submission ready", "will this plugin work when installed".
Audit and fix Claude Code SKILL.md files against enterprise compliance standards: frontmatter completeness, required body sections, and style. Use when validating or repairing skills in a plugin directory. Trigger with "audit skill", "fix skill compliance".
Learn how SKILL.md files work in Claude Code plugins, then build a production-quality agent skill from scratch. Covers frontmatter schema, body structure, testing, and iteration.
Step-by-step guide to writing a SKILL.md file for Claude Code. Learn how to plan, structure, and test auto-activating skills with proper frontmatter, allowed-tools, dynamic context injection, and supporting files.
|