feat(skills): add agenticflow-built-in-credits and agenticflow-llm-models skills

AGENTS.md

@@ -0,0 +1,205 @@
+# AGENTS.md
+
+> For AI agents contributing to this repository. If you're using the AgenticFlow CLI, see [CONTEXT.md](CONTEXT.md) instead.
+
+## Repository Overview
+
+AgenticFlow CLI — a Node.js monorepo publishing two npm packages:
+- **`@pixelml/agenticflow-cli`** (`af` / `agenticflow`) — Command-line interface for the AgenticFlow platform
+- **`@pixelml/agenticflow-sdk`** — Typed HTTP client for the AgenticFlow API
+
+Language: TypeScript (strict mode, ESM-only, target ES2022)
+License: Apache-2.0
+Node: >=18
+
+## Repository Structure
+
+```
+agenticflow-cli/
+├── packages/
+│   ├── cli/                      # @pixelml/agenticflow-cli (v1.10.4)
+│   │   ├── src/
+│   │   │   ├── bin/
+│   │   │   │   └── agenticflow.ts          # Entry point (#!/usr/bin/env node)
+│   │   │   └── cli/
+│   │   │       ├── main.ts                  # Commander program — ALL command definitions (~7700 lines)
+│   │   │       ├── client.ts               # HTTP request builder helpers
+│   │   │       ├── spec.ts                  # OpenAPI spec loader
+│   │   │       ├── local-validation.ts      # Pre-flight payload validation
+│   │   │       ├── operation-ids.ts          # Operation ID → CLI command mapping
+│   │   │       ├── changelog.ts             # Changelog rendering
+│   │   │       ├── playbooks.ts             # 14 playbook definitions
+│   │   │       ├── company-blueprints.ts    # 6 built-in workforce blueprints
+│   │   │       ├── company-io.ts            # YAML export/import/diff/merge
+│   │   │       ├── blueprint-to-agent.ts     # Blueprint → agent conversion
+│   │   │       ├── blueprint-to-workflow.ts  # Blueprint → workflow conversion
+│   │   │       ├── blueprint-to-workforce.ts # Blueprint → workforce conversion
+│   │   │       ├── pack.ts                  # Pack management
+│   │   │       ├── pack-registry.ts         # Pack registry
+│   │   │       ├── platform-catalog.ts      # Platform model catalog
+│   │   │       ├── skill.ts                 # Skill definitions
+│   │   │       ├── policy.ts                # Policy definitions
+│   │   │       ├── template-cache.ts        # Template caching
+│   │   │       ├── template-duplicate.ts    # Template duplication
+│   │   │       ├── data/
+│   │   │       │   ├── openapi.json         # Embedded OpenAPI spec (~28K lines)
+│   │   │       │   └── public_ops_manifest.json  # Public ops manifest
+│   │   │       ├── gateway/
+│   │   │       │   ├── server.ts            # Gateway server (Express-like)
+│   │   │       │   ├── connector.ts         # ChannelConnector interface
+│   │   │       │   └── connectors/          # linear.ts, webhook.ts, paperclip.ts
+│   │   │       └── utils/
+│   │   │           ├── deprecation.ts       # Deprecation warning helpers
+│   │   │           ├── mcp-inspect.ts       # MCP client classification
+│   │   │           ├── models.ts            # Model ID helpers
+│   │   │           └── patch.ts             # Partial update (merge) logic
+│   │   └── tests/                           # 19 vitest test files (mirror cli/ structure)
+│   └── sdk/                      # @pixelml/agenticflow-sdk (v1.6.0)
+│       └── src/
+│           ├── index.ts                     # Public exports + createClient() factory
+│           ├── core.ts                      # AgenticFlowSDK class — request/call/get/post/put/patch/delete/stream
+│           ├── http.ts                      # DeterministicHTTPClient
+│           ├── streaming.ts                 # Vercel AI SDK Data Stream v1 parser, AgentStream class
+│           ├── exceptions.ts                # Error hierarchy (AgenticFlowError → APIError → ValidationError, …)
+│           ├── types.ts                     # APIResponse interface
+│           └── resources/
+│               ├── index.ts                 # Barrel exports
+│               ├── agents.ts                # AgentsResource — CRUD, stream, run, patch, upload
+│               ├── agent-threads.ts         # AgentThreadsResource
+│               ├── connections.ts           # ConnectionsResource — CRUD, categories, health
+│               ├── database.ts             # DatabaseResource
+│               ├── knowledge.ts            # KnowledgeResource — CRUD, rows, search
+│               ├── marketplace.ts           # MarketplaceResource, templates
+│               ├── mcp-clients.ts           # McpClientsResource — list, get
+│               ├── node-types.ts            # NodeTypesResource — list, get, search, dynamic-options
+│               ├── paperclip.ts            # PaperclipResource — companies, agents, goals, issues
+│               ├── triggers.ts             # TriggersResource
+│               ├── uploads.ts              # UploadsResource
+│               ├── workflows.ts            # WorkflowsResource — CRUD, run, run-status
+│               └── workforces.ts           # WorkforcesResource + versions + publish sub-resources
+├── skills/                                # SKILL.md files for AI tools (agent, workforce, mcp)
+│   ├── agenticflow-agent/SKILL.md         # Single agent create/run/iterate
+│   ├── agenticflow-workforce/SKILL.md     # Multi-agent team deploy + blueprints
+│   └── agenticflow-mcp/SKILL.md           # MCP tool attach/inspect
+├── .github/workflows/
+│   ├── ci.yaml                             # CI: Python tests + Node smoke test
+│   └── release-node.yaml                   # Tag-triggered npm publish (cli-v* / sdk-v*)
+├── docs/                                   # Design docs, planning, SOPs
+├── scripts/                                # Release readiness, minion orchestrator
+├── CONTEXT.md                              # How to USE the AgenticFlow CLI (not this repo)
+└── README.md                               # Human-facing docs
+```
+
+## Build & Test
+
+```bash
+# Install dependencies
+npm ci
+
+# Build SDK first (CLI depends on it), then CLI
+npm run build
+
+# Run all tests
+npm run test
+
+# Build/test individual packages
+npm run build -w packages/sdk
+npm run build -w packages/cli
+npm run test -w packages/sdk
+npm run test -w packages/cli
+
+# Clean build artifacts
+npm run clean
+```
+
+Build order matters: **SDK must be built before CLI** since CLI imports from `@pixelml/agenticflow-sdk`.
+
+## Common Tasks
+
+### Add a new CLI command
+
+1. Add the Commander command definition in `packages/cli/src/cli/main.ts`
+2. If the command needs helper logic, create a new module in `packages/cli/src/cli/`
+3. Add the operation ID mapping in `packages/cli/src/cli/operation-ids.ts` if it wraps an API endpoint
+4. Add tests in `packages/cli/tests/` — file naming mirrors `src/cli/` (e.g., `main.test.ts`, `client.test.ts`)
+5. Build and test: `npm run build -w packages/cli && npm run test -w packages/cli`
+
+### Add a new SDK resource
+
+1. Create `packages/sdk/src/resources/<resource>.ts` — export a class extending the resource pattern
+2. Add barrel export in `packages/sdk/src/resources/index.ts`
+3. Register on the SDK class in `packages/sdk/src/core.ts`
+4. Build and test: `npm run build -w packages/sdk && npm run test -w packages/sdk`
+
+### Add a new workforce blueprint
+
+1. Define the blueprint in `packages/cli/src/cli/company-blueprints.ts`
+2. Add conversion logic in `packages/cli/src/cli/blueprint-to-workforce.ts`
+3. Add tests
+
+## Code Conventions
+
+- **TypeScript strict mode** — `strict: true` in tsconfig
+- **ESM-only** — `"type": "module"`, `NodeNext` module resolution
+- **Commander.js** for CLI argument parsing
+- **Vitest** for testing — test files in `tests/**/*.test.ts`, 10s timeout
+- **Error format** — JSON with `schema: "agenticflow.error.v1"` discriminator, always include `hint` for recovery
+- **Output format** — `--json` flag produces machine-readable output with `schema:` discriminators
+- **Never print secrets** in logs or command output
+- **No comments** in code unless explaining non-obvious behavior
+
+## Testing Patterns
+
+- Test files live in `packages/cli/tests/` and `packages/sdk/src/__tests__/`
+- File naming: `<module>.test.ts` mirrors the source module name
+- Framework: Vitest (`vitest run` for non-watch mode)
+- Tests are unit tests — no live API calls in CI
+
+## Release Process
+
+Releases are tag-triggered via GitHub Actions:
+
+| Tag pattern | Publishes | Workflow |
+|---|---|---|
+| `cli-v*` | `@pixelml/agenticflow-cli` | `.github/workflows/release-node.yaml` |
+| `sdk-v*` | `@pixelml/agenticflow-sdk` | `.github/workflows/release-node.yaml` |
+
+Steps: tag push → build → test → version set → npm publish (with provenance) → GitHub Release (auto notes)
+
+## Key Files to Know
+
+| File | Purpose |
+|---|---|
+| `packages/cli/src/cli/main.ts` | All CLI command definitions (~7700 lines) |
+| `packages/cli/src/cli/data/openapi.json` | Embedded OpenAPI spec — the source of truth for API operations |
+| `packages/cli/src/cli/company-blueprints.ts` | 6 workforce blueprints (dev-shop, marketing-agency, etc.) |
+| `packages/cli/src/cli/playbooks.ts` | 14 playbook definitions |
+| `packages/sdk/src/core.ts` | SDK client class — all HTTP methods |
+| `packages/sdk/src/resources/` | SDK resource classes (one per API domain) |
+| `CONTEXT.md` | Guide for AI agents **using** the CLI (not developing it) |
+
+## Skills
+
+SKILL.md files teach other AI tools (Claude Code, Cursor, Codex, Gemini CLI) how to *use* the `af` CLI. They live in this repo under `skills/` — next to the commands they document — so a single PR can update both the command implementation and the skill.
+
+| Skill | Path | Purpose |
+|---|---|---|
+| `agenticflow-agent` | `skills/agenticflow-agent/SKILL.md` | Single agent create/run/iterate (`af agent *`) |
+| `agenticflow-workforce` | `skills/agenticflow-workforce/SKILL.md` | Multi-agent team deploy (`af workforce *`, blueprints) |
+| `agenticflow-mcp` | `skills/agenticflow-mcp/SKILL.md` | MCP tool attach/inspect (`af mcp-clients *`) |
+
+### Sister repo deprecation: agenticflow-skill
+
+The [`agenticflow-skill`](https://github.com/PixelML/agenticflow-skill) repo previously held these same skills in a separate repository. It should be deprecated in favor of the `skills/` directory here because:
+
+- **Skills describe CLI commands** — they must change when commands change. Keeping them in the same repo means one PR updates both, eliminating sync drift.
+- **AI agents discover skills automatically** when they're local files. A separate repo requires agents to proactively clone it (they won't).
+- **The separate repo adds maintenance overhead** with no upside — same content, two locations, constant risk of divergence.
+- **Zero sync burden**: Commands and skills live together. A CLI PR that renames or changes a command updates the skill in the same commit.
+
+## Gotchas
+
+- **Build order**: SDK must be built before CLI. Root `npm run build` handles this.
+- **`main.ts` is large** (~7700 lines) — it contains all Commander command registrations. When adding commands, add them in the same file following the existing pattern.
+- **`af.sh`** at repo root runs the local build directly for dev convenience.
+- **CONTRIBUTING.md** references a Python setup — the repo has legacy Python CI artifacts; the active codebase is TypeScript.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

skills/agenticflow-agent/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: agenticflow-agent
+description: "Create, run, and iterate on a single AgenticFlow AI agent — one chat endpoint, one assistant, one persona. Use when the user wants a customer-facing bot, a support assistant, a single task agent, or a prompt experiment. Choose this skill over agenticflow-workforce when there's no orchestration between roles (no handoff, no coordinator → workers). Covers `af agent create/update/run/delete`, the `--patch` partial-update pattern for iteration, `af schema agent --field <name>` for nested payload shapes (including suggested_messages, mcp_clients, response_format), the `model_user_config` / `code_execution_tool_config` settings, and safe iteration loops."
+compatibility: Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI
+metadata:
+  author: PixelML
+  version: "3.0.0"
+  license: MIT
+triggers:
+  - "create an agent"
+  - "build an agent"
+  - "agent configuration"
+  - "system prompt"
+  - "support bot"
+  - "customer-facing bot"
+  - "single agent"
+  - "agent persona"
+  - "agent update"
+  - "patch agent"
+  - "iterate on agent"
+  - "agent run"
+  - "agent delete"
+---
+
+# AgenticFlow Agent
+
+A single AI agent with a system prompt, model, optional MCP tool attachments, and an optional code-execution sandbox. Use this when one chat surface + one set of rules is enough.
+
+## When NOT to use this skill
+
+If the user needs **multiple agents that hand off to each other** (research → write, triage → specialist, a pre-built team template), use `agenticflow-workforce` instead. Don't over-engineer — a support bot with "if billing/refunds/privacy, escalate to email" is one agent, not three.
+
+## Orient first
+
+```bash
+af bootstrap --json
+```
+
+From the response, extract:
+
+- `auth.project_id` — **required** on agent create (server does not auto-inject for agents, unlike workforces)
+- `auth.workspace_id`
+- `_links.workspace` — **surface this URL to the user right away**: *"Your AgenticFlow workspace is at `<_links.workspace>` — open it anytime to see what I'm building."* Anchors a human-first mental model before any mutation
+- `models[]` — use as source of truth for model ids (don't hardcode — they change between CLI releases)
+- `agents[]` — so you don't duplicate existing work
+
+If `data_fresh: false` in the response, the backend is degraded — don't mutate. Run `af doctor --json --strict` and fix auth/network first.
+
+## Inspect payload shape before writing
+
+```bash
+af schema agent --json
+af schema agent --field mcp_clients --json          # Nested attach shape
+af schema agent --field suggested_messages --json   # {title, label, action} — NOT strings
+af schema agent --field response_format --json      # Structured output config
+af schema agent --field update --json               # Update + null-rejected fields list
+```
+
+The `--field` drilldown returns the documented shape for a single field. Use it instead of guessing.
+
+## Create (always preview first)
+
+```bash
+af agent create --body @agent.json --dry-run --json
+af agent create --body @agent.json --json
+```
+
+Minimum valid payload:
+
+```json
+{
+  "name": "My Support Assistant",
+  "tools": [],
+  "project_id": "<from bootstrap auth.project_id>",
+  "model": "agenticflow/gemini-2.0-flash",
+  "system_prompt": "You are ..."
+}
+```
+
+**Available models** live in `af bootstrap --json > models[]` — always read from there rather than hardcoding a list in your logic (models ship between CLI releases). The CLI validates your model string at create time: typos fail fast with an actionable hint listing the known set. If you pass a `vendor/model-name`-shaped string not in the known list, it warns-but-proceeds so brand-new models work before the CLI is updated.
+
+## Run (smoke test)
+
+```bash
+af agent run --agent-id <id> --message "Test prompt" --json
+# Returns {response, thread_id, status}.
+
+af agent run --agent-id <id> --thread-id <tid> --message "continue" --json
+# Pass the same thread_id to keep conversation context; omit it to start fresh.
+```
+
+Use `af agent stream` for SSE token-level streaming if you need it; `run` is better for scripted tests.
+
+## Iterate with --patch (the cornerstone pattern)
+
+Never round-trip the full agent body to change one field:
+
+```bash
+# WRONG — full-body replace loses attached MCPs / tools / code_exec config if omitted
+af agent update --agent-id <id> --body @updated.json
+
+# RIGHT — partial update, everything else preserved
+af agent update --agent-id <id> --patch --body '{"system_prompt":"new prompt"}' --json
+af agent update --agent-id <id> --patch --body '{"model":"agenticflow/gpt-4o-mini"}' --json
+af agent update --agent-id <id> --patch --body '{"mcp_clients":[{"mcp_client_id":"<id>","run_behavior":"auto_run","tools":{}}]}' --json
+```
+
+The CLI auto-strips null-rejected fields (`knowledge`, `recursion_limit`, `task_management_config`, `suggest_replies_*`, `file_system_tool_config`, `attachment_config`, `response_format`, `skills_config`). Stripped fields are logged to stderr so bots don't think they cleared a field they didn't.
+
+## Attach an MCP tool provider
+
+See the `agenticflow-mcp` skill for the full inspect-before-attach flow. Short version:
+
+```bash
+af mcp-clients list --name-contains "google sheets" --fields id,name --json
+af mcp-clients inspect --id <mcp_id> --json
+# Only proceed if pattern != "pipedream" with write_capable_tools
+af agent update --agent-id <agent_id> --patch --body '{"mcp_clients":[{...}]}' --json
+```
+
+## Cleanup
+
+```bash
+af agent delete --agent-id <id> --json
+# Returns {"schema":"agenticflow.delete.v1","deleted":true,"id":"...","resource":"agent"}
+```
+
+## On errors
+
+Every API error returns a consistent envelope with an actionable `hint`. Common 4xx and their hints:
+
+- **404** → "Run the matching `list` command to see available IDs" (or double-check the ID)
+- **422** → "Check `details.payload` for field-level errors" (pydantic returns the offending field)
+- **401** → "Run `af whoami` / `af login`"
+
+When `hint` is non-empty, follow it before retrying.