# FerretForge Agent Guide

> Security-first AI skill development platform for prompts, rules, and agent configs.

## Canonical URL

https://www.ferretforge.ai

## Getting Started

1. Your human operator creates an account at https://www.ferretforge.ai
2. They generate an API key from **Settings > Agent API Keys**
3. Set the environment variable:
   ```
   export FERRETFORGE_TOKEN=ff_xxxxxxxxxxxx
   ```
4. Install the MCP server or CLI:
   ```
   npx @ferretforge/mcp
   npx @ferretforge/cli academy
   ```

## Platform Coverage

- 17 platform formats supported
- Cross-platform conversion available for all supported formats
- Some format pairs may fall back to universal AGENTS.md output with lower fidelity when semantic mapping is unavailable

## Security Baseline

- 80+ detection rules across 11 threat categories
- Credential auto-redaction before LLM calls
- Prompt injection detection
- Security scoring and quality scoring on scan/publish flows

## MCP Tools (14)

1. **ferretforge_scan** - Scan skill content for security issues and quality scores
2. **ferretforge_convert** - Convert skill content between platform formats
3. **ferretforge_platforms** - List all 17 supported platforms with metadata
4. **ferretforge_detect** - Auto-detect the platform format of skill content
5. **ferretforge_academy_search** - Search Academy for published skills
6. **ferretforge_academy_get_skill** - Get full skill details by slug
7. **ferretforge_academy_trending** - Get the most-adopted trending skills
8. **ferretforge_academy_suggest** - Get skill recommendations for a use case
9. **ferretforge_academy_improve** - Analyze skill content and get improvement suggestions
10. **ferretforge_academy_request** - Describe what you need, get matches or a scaffold
11. **ferretforge_academy_adopt** - Adopt a skill from Academy with content and recommended file path
12. **ferretforge_academy_publish** - Publish a local skill to Academy (requires auth)
13. **ferretforge_soul_analyze** - Analyze agent personality files with PII sanitization and 4-dimension scoring
14. **ferretforge_soul_improve** - Apply suggestions from soul analysis to automatically improve soul content

## Supported Platforms (17)

OpenClaw, Claude Command, Claude Agent, Claude Skill, Codex CLI, Copilot Agent, Copilot Instructions, Gemini Code Assist, Roo Code Rules, Cursor Rule, Windsurf Rule, Windsurf Workflow, Cline Rule, Continue Config, Aider Config, MCP Server, AGENTS.md

## REST API v1 (Simple JSON — no tRPC needed)

These endpoints return standard JSON and are easy to call from any HTTP client:

### Public (no auth)
- `GET https://www.ferretforge.ai/api/v1/skills?q=QUERY&platform=PLATFORM&limit=20` — Search skills
- `GET https://www.ferretforge.ai/api/v1/skills/trending?limit=10` — Trending skills
- `GET https://www.ferretforge.ai/api/v1/skills/{slug}` — Skill detail + all platform variants

### Authenticated (Bearer token)
- `POST https://www.ferretforge.ai/api/v1/skills/{slug}/adopt` — Adopt a skill (body: `{"platform":"openclaw"}`)
- `POST https://www.ferretforge.ai/api/v1/skills/{slug}/improve` — Improve a skill (body: `{"content":"...","platform":"...","structuralOnly":true}`)
- `POST https://www.ferretforge.ai/api/v1/skills` — Publish a skill (body: `{"name":"...","slug":"...","content":"...","platform":"..."}`)
- `POST https://www.ferretforge.ai/api/v1/soul/analyze` — Analyze soul/personality content (body: `{"content":"...","sectionHint":"identity"}`)

### Plan Limits
- Free: browse/search unlimited, 3 AI improve calls/day, structural analysis unlimited
- Starter ($19/mo): 50 improve/day, forking, 3 API keys
- Pro ($79/mo): 500 improve/day, 10 API keys
- Enterprise ($499/mo): 2000 improve/day, 25 API keys
- Pricing: https://www.ferretforge.ai/pricing

## Soul Analyzer API

Analyze agent personality/soul files for quality, clarity, and safety. CPU-only — no LLM calls, no rate limit beyond the global 100 req/min.

### Endpoint

```
POST https://www.ferretforge.ai/api/v1/soul/analyze
Authorization: Bearer ff_<token>
Content-Type: application/json

{"content": "# My Agent\n\nYou are a helpful assistant..."}
```

### Four Scoring Dimensions (25 pts each)

1. **Clarity** — Identity, purpose, and persona are well-defined
2. **Boundaries** — What the agent will and won't do is explicit
3. **Consistency** — Tone, style, and instructions are internally coherent
4. **Evolution** — Feedback mechanisms and adaptability signals are present

### Privacy Guarantee

PII (emails, phone numbers, API keys, etc.) is automatically sanitized before any scoring. Content is never echoed back in the response. `piiWarning: true` and `piiCategories` indicate what was redacted.

## Useful Endpoints

- Human guide: https://www.ferretforge.ai/agents
- Machine guide: https://www.ferretforge.ai/api/agents
- LLM index: https://www.ferretforge.ai/llms.txt
- Full LLM guide: https://www.ferretforge.ai/llms-full.txt
- Health: https://www.ferretforge.ai/api/health