Creating Skills

~/.automaton/skills/
├── web-scraper/
│   └── SKILL.md
├── github-integration/
│   └── SKILL.md
└── crypto-analysis/
    └── SKILL.md

---
name: web-scraper
description: Extract and analyze content from web pages
auto-activate: true
requires:
  bins:
    - curl
    - jq
  env:
    - SCRAPER_API_KEY
---

# Web Scraping Skill

You have the ability to scrape and analyze web pages.

## When to Use

- User asks for information from a specific URL
- Research tasks requiring web data
- Monitoring website changes

## Instructions

1. Use the `exec` tool to fetch HTML with curl
2. Parse content using grep or jq for structured data
3. Summarize findings for the user
4. Cache results to avoid redundant requests

## Example

```bash
curl -s "https://example.com" | grep -oP '(?<=<title>).*(?=</title>)'

## Frontmatter Fields

### Required Fields

#### name

Unique identifier for the skill:

```yaml
name: github-integration

description: Interact with GitHub repositories via the GitHub API

auto-activate: true  # Default: true

requires:
  bins:
    - git
    - gh
  env:
    - GITHUB_TOKEN

mkdir -p ~/.automaton/skills/my-skill

---
name: my-skill
description: A simple example skill
auto-activate: true
---

# My Custom Skill

This skill demonstrates basic functionality.

## Instructions

When the user asks about [specific topic]:

1. Use [specific tool] to gather information
2. Process the data according to [criteria]
3. Present results in [format]

## Examples

- Example usage scenario 1
- Example usage scenario 2

automaton-cli restart

automaton-cli skills list

Name          Status    Auto-Activate  Source
my-skill      enabled   yes            ~/.automaton/skills/my-skill

❌ Bad:
Handle database queries.

✅ Good:
When the user requests data from the database:

1. Use the `query_db` tool with the user's filter criteria
2. Validate the results for completeness
3. Format output as a markdown table
4. If no results, suggest alternative search terms

## Example: Fetching User Data

User: "Show me users who signed up this week"

Steps:
1. Calculate date range: `startDate = 7 days ago`
2. Query: `SELECT * FROM users WHERE created_at >= startDate`
3. Format: "Found 42 new users this week: [table]"

## When to Use This Skill

- User explicitly mentions "GitHub" or "repository"
- Task involves code version control
- User asks to create/update issues or PRs

## When NOT to Use

- General git operations (use git skill instead)
- Local repository management
- Non-GitHub version control systems

# API Integration Skill

## Authentication

All API requests must include the `X-API-Key` header.

## Rate Limiting

- Maximum 100 requests per minute
- Use exponential backoff on 429 responses
- Cache responses for 5 minutes when possible

## Error Handling

1. Catch all HTTP errors
2. Log error details
3. Provide user-friendly error messages
4. Suggest remediation steps

export function loadSkills(
  skillsDir: string,
  db: AutomatonDatabase,
): Skill[] {
  // 1. Scan skills directory
  const entries = fs.readdirSync(skillsDir);

  for (const entry of entries) {
    const skillMdPath = path.join(skillsDir, entry, "SKILL.md");
    if (!fs.existsSync(skillMdPath)) continue;

    // 2. Parse SKILL.md
    const skill = parseSkillMd(content, skillMdPath);
    if (!skill) continue;

    // 3. Check requirements
    if (!checkRequirements(skill)) {
      continue;
    }

    // 4. Upsert to database
    db.upsertSkill(skill);
  }

  return db.getSkills(true); // enabled only
}

if (skill.requires.bins) {
  for (const bin of skill.requires.bins) {
    try {
      execFileSync("which", [bin], { stdio: "ignore" });
    } catch {
      return false; // Binary not found
    }
  }
}

if (skill.requires.env) {
  for (const envVar of skill.requires.env) {
    if (!process.env[envVar]) {
      return false; // Environment variable not set
    }
  }
}

[SKILL: web-scraper — UNTRUSTED CONTENT]
Web scraping skill instructions here...
[END SKILL: web-scraper]

const sanitized = sanitizeInput(
  validated,
  `skill:${s.name}`,
  "skill_instruction"
);

automaton-cli skills list

# Disable a skill
automaton-cli skills disable web-scraper

# Enable a skill
automaton-cli skills enable web-scraper

# Remove from filesystem
rm -rf ~/.automaton/skills/web-scraper

# Remove from database
automaton-cli skills remove web-scraper

automaton-cli skills reload

export interface Skill {
  name: string;              // Unique identifier
  description: string;       // Brief summary
  autoActivate: boolean;     // Auto-inject into prompt
  requires?: SkillRequirements;
  instructions: string;      // Markdown content
  source: SkillSource;       // "builtin" | "git" | "url" | "self"
  path: string;             // Filesystem path
  enabled: boolean;         // Active status
  installedAt: string;      // ISO timestamp
}

---
name: crypto-trader
auto-activate: false
---

# Crypto Trading Skill

Activate this skill when the user explicitly requests trading operations.

**Activation phrase**: "Enable trading mode"

## Safety

- Always confirm transactions before execution
- Respect treasury policy limits
- Log all trades to audit trail

# Advanced Research Skill

This skill combines:

- **web-scraper**: For data collection
- **data-analysis**: For processing
- **report-generator**: For presentation

## Workflow

1. Use web-scraper to gather sources
2. Use data-analysis to extract insights
3. Use report-generator to format output

## API Endpoints

Base URL: `${API_BASE_URL}` (from environment)

Authentication: `Bearer ${API_TOKEN}`

## Example Request

```bash
curl -H "Authorization: Bearer ${API_TOKEN}" \
     "${API_BASE_URL}/users"

## Example Skills

### Database Query Skill

```markdown
---
name: database-query
description: Query the automaton's SQLite database
auto-activate: true
requires:
  bins:
    - sqlite3
---

# Database Query Skill

You can query your own state database at `~/.automaton/state.db`.

## Available Tables

- turns: Agent execution history
- tool_calls: Tool invocation logs
- transactions: Financial transactions
- heartbeat_schedule: Scheduled tasks

## Example Queries

Recent turns:
```sql
SELECT timestamp, state, thinking 
FROM turns 
ORDER BY timestamp DESC 
LIMIT 10;

SELECT 
  DATE(timestamp) as date,
  SUM(cost_cents) as total_cost
FROM turns
GROUP BY DATE(timestamp);

### Code Review Skill

```markdown
---
name: code-review
description: Analyze code for quality, security, and best practices
auto-activate: false
requires:
  bins:
    - git
---

# Code Review Skill

Activated for code review tasks.

## Review Checklist

### Security
- [ ] No hardcoded secrets or API keys
- [ ] Input validation on all user data
- [ ] SQL injection prevention
- [ ] XSS protection

### Code Quality
- [ ] Clear variable naming
- [ ] Function complexity under 20 lines
- [ ] Comments on complex logic
- [ ] Error handling present

### Performance
- [ ] No N+1 queries
- [ ] Efficient algorithms
- [ ] Proper indexing
- [ ] Resource cleanup

## Output Format

Provide:

1. **Summary**: Overall assessment
2. **Critical Issues**: Must fix before merge
3. **Suggestions**: Nice-to-have improvements
4. **Positive Feedback**: What's done well

---
name: self-monitoring
description: Monitor automaton health and performance
auto-activate: true
---

# Self-Monitoring Skill

## Health Checks

Periodically verify:

- Credit balance > $1.00
- No alerts in last hour
- Heartbeat tasks succeeding
- Database size < 100MB

## Alerts to Monitor

- balance_below_reserve
- heartbeat_high_failure_rate
- context_near_capacity
- zero_turns_last_hour

## Self-Healing Actions

1. **Low credits**: Trigger topup if USDC available
2. **High failure rate**: Review recent errors and adjust
3. **Context overflow**: Compress or archive old turns
4. **Zero activity**: Check for stuck processes

## Reporting

Send daily health summary to creator via social protocol.