🧩 Capabilities: Knows how to do the work
One sentence triggers an artifact. Capabilities is the layer that turns intent into execution: deterministic skills, AI-assisted skills, and sub-agents—each in the right place.
Detailed content
The Capabilities test
An AIOS passes the Capabilities test when you type a short phrase — /audit, /level-up, /onboard — and a multi-step workflow runs on its own, producing a concrete artifact: a report, plan, code, or draft. No further instructions. No micromanagement.
🎯 Operational definition
Capabilities = registered and ready skills + agents. Not what Claude could do — that's what it knows do without asking for help. The difference is having a SKILL.md (or agent file) with explicit instructions on when and how to run it.
Skills vs. Agents
These are two types of capability with distinct purposes. Understanding the difference prevents overcomplication: most cases don't need an agent — a well-written skill solves the problem in seconds, with zero model cost.
✓ Skills (.claude/skills/)
- ✓SKILL.md file with frontmatter + instructions
- ✓Run in the main session (shared context)
- ✓Ideal for sequential, deterministic tasks
- ✓Can use 0 LLM calls (pure script)
- ✓Low cost, minimal latency
⚠ Agents (.claude/agents/)
- →Sub-assistant with its own model (usually cheaper)
- →Isolated context — doesn’t pollute the main session
- →Ideal for iterative work with tools
- →Always involves LLM calls (higher cost)
- →Last resort: use the skill first
💡 Golden rule
If the task has fixed, predictable steps → skill. If it needs iterative reasoning with tools (read a file, run a command, read the result, decide the next step) → agent. When in doubt, start with a skill and evolve it only if needed.
The 3 skills included in the kit
The AIS-OS kit comes with three deliberately lean skills—each solves a real problem in the AI work cycle. They’re a starting point, not a ceiling: you build on top of them.
Initializes AIOS in a new project: creates the folder structure, generates CLAUDE.md with project context, and configures basic permissions. Run it once—then it’s ready.
Audits the current state of AIOS: checks Context, Connections, Capabilities, and Cadence. Produces a report with gaps and prioritized next steps. Run it whenever the system gets stuck.
The growth engine. Each run identifies 1 repetitive manual task and turns it into an artifact (skill, agent, script). Every artifact starts with bike-method-phase: 1 to track maturity.
Anatomy of a SKILL.md
Every skill is a Markdown file with YAML frontmatter at the top and execution instructions in the body. Claude reads the frontmatter to know when trigger and the body to know how execute.
---
name: minha-skill
description: |
Quando disparar: descreva o gatilho em linguagem
natural. O Claude usa isso para decidir se invoca
esta skill. Seja específico — evite sobreposição
com outras skills.
---
# Execução
Passo 1: Leia o contexto atual em CLAUDE.md
Passo 2: Execute [ação específica]
Passo 3: Produza o artefato em [formato/path]
Passo 4: Confirme ao usuário com resumo do feito💡 Tip: description is the skill’s brain
The field description is what Claude reads to decide whether a skill is relevant to the current message. The clearer the trigger, the lower the chance of confusion with other skills. Use example phrases that trigger it: "Use when the user asks for /onboard or the project’s initial setup."
Deterministic vs. AI-assisted
Not every skill needs AI. The principle Boring-is-Beautiful says: use the simplest solution that works. Move up the complexity ladder only when the step below isn't enough.
⚙️ Deterministic Skill
- ✓Bash/Python script — zero LLM calls
- ✓100% predictable and reproducible result
- ✓Zero cost, minimal latency (<1s)
- ✓Great for: formatting, moving files, generating boilerplate
- ✓Easy to test and debug
🤖 AI-assisted skill
- →Instruction for Claude + 1 LLM call
- →Result adapted to the current context
- →Cost of 1 call, latency of seconds
- →Great for: drafting, summarizing, analyzing, classifying
- →When the script alone can’t reason
🪜 Boring-is-Beautiful Ladder
Build capabilities via /level-up
The AIOS growth engine is the /level-up. The logic is simple: 1 run = 1 new artifact. Over time, each artifact reduces friction and increases speed.
💡 How to build a new skill
Two paths: (1) use a Anthropic's skill-creator — describe what you want and it generates the SKILL.md; (2) write it by hand using the anatomy from the previous topic. The second option is faster when you already know what you want.
🚲 bike-method-phase
Every artifact created by /level-up starts with the frontmatter bike-method-phase: 1. This signals that it’s in the bicycle phase — it works, but still needs manual attention. As it matures, it moves up a phase.
Sub-agents (.claude/agents/)
When the task requires iterative reasoning with tools — reading a file, running a command, interpreting the result, deciding the next step, and repeating — a sub-agent is the right tool. The key advantage: it runs in its own context without cluttering the main session.
🤖 Why isolated context matters
Each sub-agent has its own context window. This means long operations (auditing 50 files, iterating over a task list) don’t consume the main session’s context. You can keep chatting and giving direction while the agent works.
Use a skill when:
- ✓Steps are fixed and known before execution
- ✓Doesn’t need to reason about the intermediate result
- ✓Task is short (minutes, not hours)
- ✓Shared context is desirable
Use an agent when:
- →Requires a loop: read → execute → decide → repeat
- →Task is long and would consume the main context
- →The cheaper model is sufficient for the subtask
- →Parallelism: multiple agents at once
💡 Agent file: same structure, different location
An agent file follows the same anatomy as SKILL.md (frontmatter name + description + body), but stays in .claude/agents/. Claude knows to run it as a sub-assistant with isolated context, not as an inline instruction.
🧩 Module Summary
Next Module:
2.4 — Cadence: Runs without being asked ⏰
The final layer of the 4 Cs: automations that trigger on their own, without you having to ask.