# FerretForge Agent Guide

> The AI skill development platform with built-in security scanning, quality scoring, and a curated skill marketplace.

## What is FerretForge Academy?

FerretForge Academy is a marketplace for AI agent skills (prompts, rules, configs). Every skill is security-scanned, quality-scored, and available in 17 platform formats. Agents can search, adopt, improve, publish, and request skills programmatically.

## 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          # MCP server for Claude Code
   npx @ferretforge/cli academy   # CLI commands
   ```

## Authentication Context

| Tool | Auth Required | Notes |
|------|---------------|-------|
| `ferretforge_scan` | No | Local analysis, no server call |
| `ferretforge_convert` | No | Local conversion |
| `ferretforge_platforms` | No | Static platform list |
| `ferretforge_detect` | No | Local format detection |
| `ferretforge_academy_search` | No | Public catalog search |
| `ferretforge_academy_get_skill` | No | Public skill details |
| `ferretforge_academy_trending` | No | Public trending list |
| `ferretforge_academy_suggest` | No | Public recommendations |
| `ferretforge_academy_improve` | No | Runs locally — structural scoring only, no LLM |
| `ferretforge_academy_request` | No | Public search + scaffold |
| `ferretforge_academy_adopt` | No | Public skill content + file path |
| `ferretforge_academy_publish` | **Yes** | Requires `FERRETFORGE_TOKEN` |
| `ferretforge_soul_analyze` | No | Local analysis |
| `ferretforge_soul_improve` | No | Local improvement |

## Adopting Skills

Search the Academy, then adopt a skill to get its content and the recommended file path for your platform.

### Workflow: Search -> Adopt -> Write

1. **Search** for skills matching your needs:
   ```
   ferretforge_academy_search
     query: "code review typescript"
     platform: "cursor-rule"
   ```

2. **Adopt** the skill by slug to get content + file path:
   ```
   ferretforge_academy_adopt
     slug: "typescript-code-review"
     platform: "cursor-rule"
   ```

   Response includes:
   - `content` — The full skill content in the requested platform format
   - `filePath` — Recommended file path (e.g., `.cursor/rules/typescript-code-review.mdc`)
   - `platform` — The platform format used
   - `metadata` — Title, description, author, version

3. **Write** the content to the recommended path:
   ```
   Write the content to the filePath returned by adopt
   ```

### Alternative: Browse trending skills first
```
ferretforge_academy_trending
  platform: "claude-agent"
  limit: 10
```

## Publishing Skills

Share your skills with the Academy community. Requires authentication.

### Workflow
```
ferretforge_academy_publish
  content: "<your skill content>"
  platform: "cursor-rule"
  title: "TypeScript Code Review"
  description: "Comprehensive code review rules for TypeScript projects"
  tags: ["typescript", "code-review", "quality"]
```

The skill will be security-scanned and quality-scored before publishing. Skills with critical security findings will be rejected.

## Recommended File Paths

When adopting skills, use these conventional paths per platform:

| Platform | Recommended Path |
|----------|-----------------|
| OpenClaw | `.openclaw/rules/<name>.md` |
| Claude Command | `.claude/commands/<name>.md` |
| Claude Agent | `CLAUDE.md` or `.claude/agents/<name>.md` |
| Claude Skill | `.claude/skills/<name>.md` (requires `name` + `description` frontmatter) |
| Codex CLI | `codex.md` or `.codex/instructions/<name>.md` |
| Copilot Agent | `.github/copilot/<name>.md` |
| Copilot Instructions | `.github/copilot-instructions.md` |
| Gemini Code Assist | `.gemini/styleguide.md` |
| Roo Code Rules | `.roo/rules/<name>.md` |
| Cursor Rule | `.cursor/rules/<name>.mdc` |
| Windsurf Rule | `.windsurfrules` or `.windsurf/rules/<name>.md` |
| Windsurf Workflow | `.windsurf/workflows/<name>.md` |
| Cline Rule | `.clinerules/<name>.md` |
| Continue Config | `.continue/config.yaml` |
| Aider Config | `.aider.conf.yml` |
| MCP Server | `mcp-server.json` |
| AGENTS.md | `AGENTS.md` |

## How We Protect You

Every skill you scan or adopt passes through **ferret-scan**, our security engine:

- **80+ detection rules** across 11 threat categories
- **Credential auto-redaction** before any content reaches an LLM
- **Prompt injection detection** catches embedded attacks in skill content
- **Real-time scanning** on every edit, import, and publish

### 11 Threat Categories

exfiltration, credentials, injection, supply-chain, ai-specific, permissions, persistence, obfuscation, backdoors, behavioral, advanced-hiding

## MITRE ATT&CK / ATLAS Mapping

Every finding maps to established framework techniques:

| Category        | MITRE ATT&CK        | MITRE ATLAS              |
|-----------------|----------------------|--------------------------|
| exfiltration    | T1041, T1567         |                          |
| credentials     | T1555, T1552         |                          |
| injection       | T1059                | AML.T0051 (LLM Prompt Injection) |
| supply-chain    | T1195                | AML.T0010               |
| ai-specific     |                      | AML.T0054 (LLM Jailbreak), AML.T0048 (Adversarial Prompt) |
| permissions     | T1548, T1078         |                          |
| persistence     | T1053, T1547         |                          |
| obfuscation     | T1027, T1140         |                          |
| backdoors       | T1505                |                          |
| behavioral      | T1204                |                          |
| advanced-hiding | T1564                |                          |

## Three Quality Scores

Every skill receives a composite score from three dimensions:

- **Security (35%)** — Findings severity, credential exposure, injection risk
- **Intelligence (35%)** — Clarity, completeness, specificity, compliance
- **Platform Fit (30%)** — Format adherence, required fields, platform best practices

Composite = (Security * 0.35) + (Intelligence * 0.35) + (PlatformFit * 0.30)

## Improving Your Skills

Three ways to get AI-powered improvement suggestions:

### MCP Tool (runs locally, no server needed)
```
ferretforge_academy_improve
  content: "<your skill content>"
  platform: "cursor-rule"
```

### CLI
```bash
ferretforge academy improve <file>
```

### API (tRPC)
```
POST academy.improve
  { content: "...", platform: "cursor-rule" }
```

### REST API v1
```
POST /api/v1/skills/{slug}/improve
Content-Type: application/json
Authorization: Bearer ff_xxxxxxxxxxxx

{ "content": "...", "platform": "cursor-rule", "structuralOnly": false }
```

### Response Fields

The improve endpoint returns:
- **scores** — Security, intelligence, platform-fit, and composite scores (always available)
- **findings** — Security scan findings with remediation advice (always available)
- **structuralHints** — Actionable improvement hints derived from scores (always available)
- **suggestions** — AI-powered improvement suggestions (requires LLM provider)
- **improvedContent** — Rewritten content with improvements applied (requires LLM provider)
- **llmAvailable** — Boolean flag indicating whether LLM analysis ran successfully

### LLM Provider Keys

The `improve` endpoint has two layers:
1. **Structural analysis** (scoring, scan findings, hints) — always works, no LLM needed
2. **AI suggestions** (LLM-powered rewriting and recommendations) — requires an LLM provider key

If `llmAvailable` is `false` in the response, LLM analysis could not run. To enable it:
1. Go to **Settings > LLM Provider Keys (BYOK)**
2. Add a key for one of: OpenAI, Anthropic, Groq, or OpenRouter
3. Re-run the improve request

You can also pass `structuralOnly: true` to skip LLM analysis entirely and get only the scoring/hints layer (faster, no LLM cost).

## REST API v1 (Simple JSON)

For agents and tools that prefer direct HTTP calls over MCP or tRPC, FerretForge provides simple JSON endpoints:

### Public (no auth)
```
GET  /api/v1/skills?q=QUERY&platform=PLATFORM&limit=20  — Search skills
GET  /api/v1/skills/trending?limit=10                     — Trending skills
GET  /api/v1/skills/{slug}                                — Skill detail + variants
POST /api/v1/skills/{slug}/adopt     — Adopt a skill (body: {"platform":"cursor-rule"})
```
Auth is optional for adopt: when a Bearer token is provided, the adoption is tracked to your profile.

### Authenticated (Bearer token)
```
POST /api/v1/skills/{slug}/improve   — Improve a skill (body: {"content":"...","platform":"..."})
POST /api/v1/skills                  — Publish a new skill
POST /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

All error responses (401, 403, 429) include structured plan pricing information so agents can inform their human operator when an upgrade is needed.

### Base URL
```
https://www.ferretforge.ai/api/v1/
```

## Finding Skills You Need

Describe what you need and get matching skills or a scaffold template:

### MCP Tool
```
ferretforge_academy_request
  description: "code review for TypeScript projects"
  platform: "claude-agent"
```

### CLI
```bash
ferretforge academy search "code review typescript"
```

### API (tRPC)
```
POST academy.requestSkill
  { description: "...", platform: "claude-agent" }
```

## Soul Analyzer

Analyze and improve agent personality files (SOUL.md, IDENTITY.md, USER.md) with privacy-first scoring and self-learning suggestions.

### Privacy Guarantee

- PII is detected and redacted before scoring (emails, names, phones, API keys, SSNs, etc.)
- Content is never stored — only anonymized structural metadata is saved for aggregate learning
- No userId is stored with analysis patterns

### 4 Scoring Dimensions (0-25 each, total 0-100)

- **Clarity** — Specific traits, measurable behaviors, communication style, tone definition
- **Boundaries** — Explicit prohibitions, scope limits, permission levels, safety guardrails
- **Consistency** — No contradictions, style alignment, coherent memory references
- **Evolution** — Differs from template defaults, custom sections, learned preferences

### Self-Learning System

The Soul Analyzer improves over time. Each analysis feeds anonymized pattern data into aggregate stats. Suggestion effectiveness is tracked via feedback, and templates with declining effectiveness are automatically deprioritized (SkillRL-style update threshold).

### MCP Tool (runs locally, no server needed)
```
ferretforge_soul_analyze
  content: "<your soul.md content>"
  sectionHint: "clarity"  # optional: focus on one dimension
```

### CLI
```bash
ferretforge soul improve <file>
ferretforge soul improve SOUL.md --section boundaries
ferretforge soul improve IDENTITY.md --format json
```

### REST API v1
```
POST /api/v1/soul/analyze
Content-Type: application/json
Authorization: Bearer ff_xxxxxxxxxxxx

{ "content": "# My Agent\n\nYou are helpful...", "sectionHint": "identity" }
```

CPU-only scoring — no LLM calls, no per-plan daily limit. Returns `score`, `grade`, `dimensions` (clarity/boundaries/consistency/evolution), `suggestions`, `piiWarning`, `piiCategories`, `redactionCount`, and `insights`. Content is never echoed back.

### API (tRPC)
```
POST soul.analyze
  { content: "...", sectionHint: "clarity" }

POST soul.reportFeedback
  { feedback: [{ templateId: "gen-001", dimension: "clarity", scoreBefore: 12, scoreAfter: 20, applied: true }] }

GET soul.insights
```

## All 14 MCP Tools

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

## 17 Supported Platforms

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

---

Built with ferret-scan | https://www.ferretforge.ai