Skills are markdown files that teach the agent domain-specific knowledge and behavioral patterns. They live in ~/.picobot/workspace/skills/{name}/SKILL.md and are loaded into the system prompt when relevant.

How Skills Work¶

Each skill has a SKILL.md with YAML frontmatter:

---
name: my-skill
description: What this skill does
tags: [relevant, keywords]
metadata: '{"picobot": {"always": true}}'
---

Instructions for the agent...

Loading behavior: - Skills with always: true in metadata are loaded into every system prompt at full length - All other skills appear as a summary list (name + description) — the agent reads the full SKILL.md on demand when it decides the skill is relevant

Progressive disclosure: Complex skills use a references/ subdirectory for detailed reference material. The main SKILL.md provides core instructions and links to references that the agent reads when needed. This keeps the system prompt manageable.

Built-in Skills¶

TODO Tracking (always on)¶

Name: todo | Always loaded: Yes

Tracks multi-step tasks via ~/.picobot/workspace/TODO.md. This is the only always-on skill because TODO.md is injected into every system prompt — it's the agent's short-term memory that survives context compression.

When to use: Tasks with 3+ steps, sub-agent delegation, sequential work, anything that spans multiple turns.

Format:

## Task Title
- [ ] Step one
- [ ] Step two
- [x] Completed step

The entire ## Task Title section is removed when all items are checked off.

Knowledge Base Protocol¶

Name: kb

Teaches the agent how to use the KB effectively. Core principle: always search before store. Includes topic selection guidance, entry quality standards, and curation tasks.

See Knowledge Base for full KB documentation.

Cron Scheduling¶

Name: cron

Teaches the agent to schedule recurring tasks. Includes schedule format reference (interval seconds vs cron expressions) and common conversion examples.

See Scheduling for full scheduling documentation.

Self-Improvement Pipeline¶

Three skills form a pipeline where raw observations are progressively refined into stable knowledge:

self-reflect (capture) → self-evaluate (score) → self-improve (promote)

self-reflect¶

Analyzes recent session history to extract patterns. Reads the last 20-30 exchanges looking for:

• Corrections — user said "no, I meant..."
• Failures — tool errors, bad assumptions
• Successes — praised or completed tasks
• Preferences — explicit or implicit user preferences
• Knowledge gaps — things the agent should have known

Each pattern is stored as a raw observation in journal/. These are captures, not conclusions — they'll be processed later by self-improve.

self-evaluate¶

Scores recent interactions on 5 dimensions (1-5 scale):

Evaluations are stored in self/ as stable knowledge. The skill tracks trends over time — comparing scores to previous evaluations to identify improving and declining dimensions.

self-improve¶

The promotion step. Reads evaluations and reflections, then takes concrete actions:

Safety: Never modifies picobot source code, never deletes KB entries, proposes uncertain changes for review rather than acting directly.

Running the Pipeline¶

The agent can run any skill individually, but the full pipeline is:

1. Ask the agent to self-reflect (or schedule it via cron)
2. Ask the agent to self-evaluate
3. Ask the agent to self-improve

Each step builds on the previous one's output. You can also schedule this as a cron job:

picobot cron add "Run the self-improvement pipeline: reflect, evaluate, improve" --cron "0 22 * * 5"

This runs every Friday at 10 PM — a weekly self-improvement cycle.

Accessibility Testing¶

Name: a11y

Conducts WCAG 2.2 AA accessibility audits using the browser tool. Three modes:

Quick Scan: Inject axe-core via browser(action="evaluate"), collect violations by severity (critical, serious, moderate, minor). Fast, automated-only.

Full Audit: Four phases: 1. Automated axe-core scan 2. Keyboard navigation — Tab through all elements, verify focus order, check skip links 3. Focus management — modals trap focus correctly, Escape closes them, focus returns to trigger 4. ARIA pattern testing — identify widgets by role (tablist, menu, dialog, combobox), test keyboard interactions

Regression Check: Scan, load previous baseline from KB, diff, store updated baseline. Catches new violations introduced since the last audit.

Reference files: - references/axe-rules.md — axe-core rule reference indexed by impact level - references/keyboard-patterns.md — WAI-ARIA keyboard interactions for common widgets - references/report-template.md — audit report format

Example usage:

Run a full accessibility audit on https://example.com

Test Automation¶

Name: test-automation

Write and run browser tests from natural language specifications. Three modes:

Single Test: Translate a plain English spec into browser actions and assertions.

Test that clicking "Add to Cart" on the product page increases the cart count by 1

Visual Regression: Capture screenshot baselines, then compare on subsequent runs using vision to detect layout, content, and styling changes.

Suite Run: Execute all tests (or a tagged subset) from ~/.picobot/workspace/tests/.

Key feature — self-healing selectors: When a CSS selector breaks, the agent tries a fallback chain: [name] → [role] + accessible name → text content → placeholder → label → semantic element → class → XPath. Tests survive markup changes because the agent finds elements by purpose, not by CSS class.

Reference files: - references/selector-strategies.md — selector fallback chain with stability ratings - references/test-patterns.md — common patterns (forms, auth, CRUD, pagination, modals) - references/report-template.md — test report format

Summarization¶

Name: summarize

Summarize or extract text from URLs, PDFs, and YouTube videos using the external summarize tool. Supports length control (short|medium|long|xl|xxl), multiple LLM backends, and Firecrawl fallback for difficult pages.

Creating Custom Skills¶

Skills are just markdown files. To create one:

1. Create ~/.picobot/workspace/skills/my-skill/SKILL.md
2. Add YAML frontmatter (name, description, tags)
3. Write instructions in markdown
4. Optionally add references/ for detailed material
5. Set metadata: '{"picobot": {"always": true}}' if it should always be loaded

The agent can also create and edit its own skills — this is how the self-improvement pipeline works. The agent literally rewrites its own instructions based on what it learns.