Pss Agent Toml

---
name: pss-agent-toml
description: "Use when creating .agent.toml profiles for Claude Code agents. Trigger with /pss-setup-agent. AI selects elements across 6 types, validates coherence, produces conflict-free profiles."
argument-hint: "<agent-path> [--requirements PATH...]"
user-invocable: false
---

# PSS Agent TOML Profile Builder

## Overview

An `.agent.toml` file defines the complete configuration profile for a Claude Code agent: which skills it should use, which sub-agents complement it, which slash commands enhance its workflow, which rules constrain its behavior, which MCP servers extend its capabilities, and which LSP servers support its languages.

## FUNDAMENTAL PRINCIPLE: AI Agent is ALWAYS Required

**An AI agent MUST be the decision-maker for element selection.** No mechanical script or automated pipeline can produce a correct agent profile. Here is why:

1. **Conflict detection requires reasoning**: A script cannot determine that "jest-testing" and "vitest-testing" are mutually exclusive, or that a "database-management" skill is redundant when a "postgres-mcp" server is already included.

2. **Use case prediction requires understanding**: Choosing the right skills means predicting what the agent will actually encounter — a "security auditor" working on a healthcare app needs HIPAA compliance skills that no keyword matcher would surface.

3. **Cross-type coherence requires judgment**: A skill, an MCP server, and an agent can all provide "browser automation" — deciding which combination to keep requires reading their actual content and understanding the trade-offs.

4. **Framework/runtime compatibility requires knowledge**: Knowing that Vitest is the correct test runner for a Vite-based project, or that Bun replaces npm/yarn, requires real-world understanding that no scoring algorithm provides.

**The Rust binary provides scored candidates. The AI agent makes the decisions.** This is the same principle as the prompt hook: the binary suggests, Claude chooses.

This skill teaches ANY agent or Claude model how to:
1. **Search** the element index to find candidates for each section
2. **Evaluate** candidates by reading their actual SKILL.md/agent.md content
3. **Compare** alternatives to resolve conflicts — including cross-type overlap detection
4. **Add** specific elements from any source (local, marketplace, GitHub, network)
5. **Validate coherence** — ensure no overlapping, conflicting, or redundant elements across ALL types
6. **Assemble** and validate the final `.agent.toml` file

**Default mode is autonomous**: the agent executes the full pipeline, makes all decisions, produces the `.agent.toml`, and reports the result. Interactive collaboration with the user or orchestrator is optional — it only happens when explicitly requested or when truly unresolvable conflicts are detected.

## Prerequisites

- **Skill index must exist**: `~/.claude/cache/skill-index.json` — run `/pss-reindex-skills` if missing
- **PSS Rust binary must be built**: Located at `$CLAUDE_PLUGIN_ROOT/rust/skill-suggester/bin/<platform>`
- **Agent definition file**: The `.md` file describing the agent to profile

---

## Quick Start

The fastest path uses the `/pss-setup-agent` command, which spawns a profiler agent:

```
/pss-setup-agent /path/to/agent.md --requirements /path/to/prd.md
```

For full control, follow the step-by-step process below.

---

## The .agent.toml Format

Every `.agent.toml` has these sections:

```toml
# Auto-generated by PSS Agent Profiler
# Agent: <name>
# Generated: <timestamp>

[agent]                    # REQUIRED: Agent identification
name = "my-agent"          # kebab-case, matches ^[a-z0-9][a-z0-9_-]*$
source = "path"            # "path" or "plugin:<name>"
path = "/abs/path/to/my-agent.md"

[requirements]             # OPTIONAL: Project context used for profiling
files = ["prd.md"]         # Basenames of requirement files
project_type = "web-app"   # web-app, cli-tool, mobile-app, library, api, microservice
tech_stack = ["typescript", "react", "postgresql"]

[skills]                   # REQUIRED: Tiered skill recommendations
primary = ["skill-a", "skill-b"]        # Max 7 — core daily-use skills (score >= 60%)
secondary = ["skill-c", "skill-d"]      # Max 12 — useful common tasks (score 30-59%)
specialized = ["skill-e"]               # Max 8 — niche situations (score 15-29%)

[skills.excluded]          # OPTIONAL: Transparency — why certain skills were rejected
# "vue-frontend" = "Conflicts with React (requirements specify React)"
# "jest-testing" = "Vitest preferred for Vite-based project"

[agents]                   # OPTIONAL: Complementary sub-agents
recommended = ["sleuth", "e2e-tester"]

[commands]                 # OPTIONAL: Recommended slash commands
recommended = ["commit", "describe-pr"]

[rules]                    # OPTIONAL: Enforcement rules
recommended = ["claim-verification", "observe-before-editing"]

[mcp]                      # OPTIONAL: MCP servers for extended capabilities
recommended = ["chrome-devtools"]

[hooks]                    # OPTIONAL: Hook configurations
recommended = []

[lsp]                      # OPTIONAL: Language servers (assigned by language detection)
recommended = ["typescript-lsp", "pyright-lsp"]
```

**Schema reference**: `$CLAUDE_PLUGIN_ROOT/schemas/pss-agent-toml-schema.json`
**Validator**: `uv run scripts/pss_validate_agent_toml.py <file> --check-index --verbose`

---

## Step-by-Step Profile Building Process

### Phase 1: Gather Context

**1.1 Read the agent definition file**

Read the agent's `.md` file completely. Extract:
- **name**: From YAML frontmatter `name:` field or filename stem
- **description**: From frontmatter `description:` or first non-heading paragraph
- **role**: developer, tester, reviewer, deployer, designer, security, data-scientist
- **duties**: From bullet lists under headings containing "responsibilities", "duties", "tasks"
- **tools**: From frontmatter `tools:` / `allowed-tools:` or tool mentions in body
- **domains**: From frontmatter or inferred (security, frontend, backend, devops, data, etc.)

**1.2 Read requirements documents** (if available)

Read all provided design/requirements files. Extract:
- **project_type**: What is being built (web-app, mobile-app, cli-tool, library, etc.)
- **tech_stack**: Specific technologies, frameworks, languages
- **key features**: Core capabilities the project needs
- **constraints**: Performance, compliance, platform targets

**1.3 Detect project languages from cwd**

Scan the working directory for:
- `package.json` / `tsconfig.json` → TypeScript/JavaScript
- `pyproject.toml` / `setup.py` → Python
- `Cargo.toml` → Rust
- `go.mod` → Go
- `*.swift` / `Package.swift` → Swift
- `pom.xml` / `build.gradle` → Java
- `CMakeLists.txt` → C/C++

This determines LSP server assignment.

**Phase 1 Completion Checklist** — Copy this checklist and track your progress (ALL items must be checked before proceeding to Phase 2):

- [ ] Agent `.md` file has been read in full (not just frontmatter)
- [ ] `name` extracted (from frontmatter `name:` or filename stem)
- [ ] `description` extracted (frontmatter or first non-heading paragraph)
- [ ] `role` classified (developer/tester/reviewer/deployer/designer/security/data-scientist)
- [ ] `duties` extracted (bullet lists under responsibilities/duties/tasks headings)
- [ ] `tools` extracted (from frontmatter `tools:`/`allowed-tools:` or tool mentions in body)
- [ ] `domains` extracted or inferred (security/frontend/backend/devops/data/etc.)
- [ ] All `--requirements` files have been read in full (or confirmed: no requirements provided)
- [ ] `project_type` identified from requirements (web-app/cli-tool/mobile-app/library/api/microservice)
- [ ] `tech_stack` extracted from requirements (specific frameworks, languages, databases)
- [ ] `key_features` noted from requirements (features that drive skill selection)
- [ ] `constraints` noted from requirements (performance, compliance, platform targets)
- [ ] Project languages detected from cwd (presence of Cargo.toml/package.json/pyproject.toml/go.mod/etc.)
- [ ] LSP server assignment pre-determined from detected languages

**If ANY item is unchecked: re-read the relevant file before proceeding.**

---

### Phase 2: Get Candidates from the Index

**2.1 Invoke the Rust binary for scored candidates**

Build a JSON descriptor and invoke the binary:

```bash
# $$ = current shell PID, ensures unique temp file per session
cat > /tmp/pss-agent-profile-input-$$.json << 'EOF'
{
  "name": "<agent-name>",
  "description": "<agent description + requirements summary>",
  "role": "<role>",
  "duties": ["<duty1>", "<duty2>"],
  "tools": ["<tool1>", "<tool2>"],
  "domains": ["<domain1>", "<domain2>"],
  "requirements_summary": "<condensed requirements text, max 2000 chars>",
  "cwd": "<absolute path to working directory>"
}
EOF

# Invoke binary — returns up to 30 scored candidates grouped by type
"$BINARY_PATH" --agent-profile /tmp/pss-agent-profile-input-$$.json --format json --top 30
```

The binary returns scored candidates grouped by type:
```json
{
  "agent": "name",
  "skills": {
    "primary": [{"name":"...", "score":0.85, "confidence":"HIGH", "evidence":["keyword:docker"], "description":"..."}],
    "secondary": [...],
    "specialized": [...]
  },
  "complementary_agents": ["agent-x"],
  "commands": [{"name":"...", "score":0.6, ...}],
  "rules": [{"name":"...", "score":0.5, ...}],
  "mcp": [{"name":"...", "score":0.4, ...}],
  "lsp": [{"name":"...", "score":0.3, ...}]
}
```

**CRITICAL**: These are CANDIDATES, not final selections. The binary scores by keyword/intent matching only. YOU must now evaluate each candidate intelligently.

**2.2 Search for additional candidates**

If the binary output doesn't cover a known need from the requirements, search the index directly:

```bash
# Powerful multi-field index search — supports type, category, language, framework filters
cat ~/.claude/cache/skill-index.json | python3 -c "
import json, sys

idx = json.load(sys.stdin)
args = sys.argv[1:]
query = None
filters = {}
for i, a in enumerate(args):
    if a.startswith('--type='):       filters['type'] = a.split('=',1)[1]
    elif a.startswith('--category='): filters['category'] = a.split('=',1)[1]
    elif a.startswith('--language='): filters['languages'] = a.split('=',1)[1]
    elif a.startswith('--framework='): filters['frameworks'] = a.split('=',1)[1]
    elif not a.startswith('--'):    query = a.lower()

for name, e in idx['skills'].items():
    # Apply filters first (exact match on structured fields)
    if 'type' in filters and e.get('type','') != filters['type']:
        continue
    if 'category' in filters and e.get('category','') != filters['category']:
        if filters['category'] not in e.get('secondary_categories', []):
            continue
    if 'languages' in filters and filters['languages'] not in e.get('languages', []):
        continue
    if 'frameworks' in filters and filters['frameworks'] not in e.get('frameworks', []):
        continue
    # Then keyword search across multiple fields
    if query:
        searchable = ' '.join([
            name,
            e.get('description', ''),
            ' '.join(e.get('keywords', [])),
            ' '.join(e.get('use_cases', [])),
            ' '.join(e.get('intents', [])),
            e.get('category', ''),
        ]).lower()
        if query not in searchable:
            continue
    cat = e.get('category', '?')
    typ = e.get('type', 'skill')
    print(f'{typ:8} {cat:16} {name:30} {e.get(\"description\",\"\")[:55]}')
" "<search-term>" [--type=skill|agent|command|rule|mcp|lsp] [--category=<category>] [--language=<language>] [--framework=<framework>]
```

**Search examples:**
- `"websocket"` — find all elements mentioning websocket
- `"testing" --type=skill` — find only skills related to testing
- `"" --category=security` — list all elements in the security category
- `"react" --framework=react` — find React-specific elements
- `"" --language=python --type=skill` — find all Python skills

**Phase 2 Completion Checklist** (ALL items must be checked before proceeding to Phase 3):

- [ ] Temporary JSON descriptor written with session-unique filename (use PID suffix: `pss-agent-profile-input-$$.json`)
- [ ] Descriptor contains all 8 fields: `name`, `description`, `role`, `duties`, `tools`, `domains`, `requirements_summary`, `cwd`
- [ ] `requirements_summary` is 2000 characters or fewer (truncate if needed)
- [ ] Rust binary invoked with `--agent-profile`, `--format json`, `--top 30`
- [ ] Binary returned exit code 0 (non-zero = STOP and report error)
- [ ] Binary output is valid JSON (parse to verify)
- [ ] Candidates grouped by type: `skills`, `complementary_agents`, `commands`, `rules`, `mcp`, `lsp` all present
- [ ] Candidate count per type noted (for gap analysis in Phase 3)
- [ ] Additional manual index search performed for any known needs not covered by binary output

**If binary fails: do NOT proceed. Report the error and stop.**

---

### Phase 3: Evaluate Each Candidate (AI Reasoning Required)

**This phase is WHY an AI agent is mandatory.** For every candidate returned by the binary, you must:

**3.1 Read the candidate's source file**

For each skill/agent/command/rule candidate, read its actual `.md` file (the path is in the index entry or binary output). Understand:
- What does this element ACTUALLY do (not just what the keywords suggest)?
- What frameworks/runtimes/languages does it target?
- What tools does it use or assume are available?
- What is its scope — broad or narrow?

**3.2 Evaluate relevance to the agent's role**

Ask yourself:
- Does this element solve a problem the agent will ACTUALLY encounter?
- Is it relevant to the project's tech stack and domain?
- Is it the RIGHT tool for the job, or just a keyword match?
- Would a human developer working in this role want this element?

**3.3 Detect mutual exclusivity**

These element families are mutually exclusive — only ONE from each group:

| Category | Alternatives |
|----------|-------------|
| JS Framework | React, Vue, Angular, Svelte, Solid |
| JS Runtime | Node, Deno, Bun |
| JS Bundler | Webpack, Vite, esbuild, Parcel, Turbopack |
| CSS Framework | Tailwind, Bootstrap, Bulma, Chakra UI |
| ORM | Prisma, TypeORM, Drizzle, Sequelize |
| Testing | Jest, Vitest, Mocha, Jasmine |
| State Mgmt | Redux, Zustand, MobX, Recoil, Jotai |
| Deployment | Vercel, Netlify, AWS, GCP, Azure |
| Python Web | Django, Flask, FastAPI, Starlette |
| Python Test | pytest, unittest, nose2 |
| Mobile | React Native, Flutter, SwiftUI, Kotlin Compose |

**Resolution rule**: Keep the one that matches the tech_stack in requirements. If no requirements, keep the highest-scored and document alternatives in `[skills.excluded]`.

**3.4 Check for obsolescence**

Flag elements that reference:
- Deprecated APIs or patterns (componentWillMount, var, require() in ESM)
- End-of-life runtimes (Python 2, Node 14)
- Superseded tools (TSLint → ESLint, Moment.js → Luxon/date-fns)

Use WebSearch to verify if unsure: "Is <library> deprecated in 2026?"

**3.5 Verify stack compatibility**

- Python-only skill for a TypeScript project → REMOVE
- iOS skill for a web-only project → REMOVE
- React skill when requirements specify Vue → REMOVE
- AWS deployment skill when requirements specify Vercel → REMOVE

**3.6 Identify gaps and search for missing elements**

After reviewing candidates, check if requirements mention needs not covered:
- "real-time" → search for WebSocket/SSE skills
- "i18n" → search for internationalization skills
- "HIPAA" / "PCI" → search for compliance/security skills
- "PDF generation" → search for document processing skills
- "accessibility" → search for WCAG/a11y skills

Search the index for each gap and add qualified matches.

**3.7 Prune redundancy**

If skill A covers everything skill B does plus more, remove skill B. Example: `exhaustive-testing` subsumes `unit-testing` — keep only `exhaustive-testing`.

**Phase 3 Completion Checklist** (ALL items must be checked before proceeding to Phase 4):

- [ ] Every candidate's SKILL.md/agent.md has been READ IN FULL (not just the binary's description)
- [ ] Every candidate evaluated: "Does this solve a problem this agent will ACTUALLY encounter?"
- [ ] Mutual exclusivity checked for ALL 11 families (JS framework, runtime, bundler, CSS, ORM, testing, state mgmt, deployment, Python web, Python test, mobile)
- [ ] Only ONE element remains from each mutually exclusive family
- [ ] Obsolescence/deprecation check completed for all candidates
- [ ] Stack compatibility verified: no cross-stack elements (Python skill for TS project, iOS for web, etc.)
- [ ] Gap analysis done: every key requirement scanned for missing coverage
- [ ] Redundancy pruning done: no strict-subset skills remain alongside their superset
- [ ] Final candidates list assembled with intended tier assignment (primary/secondary/specialized)

**If ANY candidate was NOT individually read: go back and read it before proceeding.**

---

### Phase 4: Add Elements from External Sources

Elements not in the current index can be added from local paths, installed plugins, marketplace plugins, GitHub repos, network shares, or raw URLs. For each source, read and evaluate the element using the same Phase 3 criteria before adding.

See [references/external-sources.md](references/external-sources.md) for detailed instructions and the Phase 4 Completion Checklist.

---

### Phase 5: Cross-Type Coherence Validation

**This is the most critical phase.** Validate that no overlaps or conflicts exist BETWEEN types (skill<->MCP, skill<->agent, agent<->agent, MCP<->MCP, rule<->rule). Check all 13 items on the coherence checklist.

See [references/cross-type-coherence.md](references/cross-type-coherence.md) for detailed overlap detection rules, the coherence checklist, and resolution strategies.

---

### Phase 6: Write and Validate

**6.1 Write the `.agent.toml` file**

Use the template from "The .agent.toml Format" section above. Every field must be populated from the evaluation results. The `[skills.excluded]` section must document WHY each rejected candidate was excluded.

**6.2 Validate**

Run the validator:
```bash
uv run scripts/pss_validate_agent_toml.py <output-path> --check-index --verbose
```

Exit codes: 0 = valid, 1 = errors found, 2 = TOML parse error.

If validation fails, fix the errors and re-validate. Common issues:
- Missing required sections (`[agent]`, `[skills]`)
- Duplicate skill across tiers (same name in primary AND secondary)
- Tier size exceeded (primary > 7, secondary > 12, specialized > 8)
- Agent name not kebab-case

**6.3 Clean up**

Delete the temporary JSON descriptor file.

**Phase 6 Completion Checklist** (profile is ONLY complete when ALL items are checked):

- [ ] `.agent.toml` file written to the correct output path
- [ ] `[agent]` section has `name`, `source`, `path` — all correct
- [ ] `[requirements]` section present if requirements were provided; omitted if none
- [ ] `[skills]` section: `primary` has 1-7 items, `secondary` has 0-12, `specialized` has 0-8
- [ ] `[skills.excluded]` has a comment for every rejected candidate with the rejection reason
- [ ] ALL optional sections present: `[agents]`, `[commands]`, `[rules]`, `[mcp]`, `[hooks]`, `[lsp]` (even if `recommended = []`)
- [ ] Validator run: `uv run "$CLAUDE_PLUGIN_ROOT/scripts/pss_validate_agent_toml.py" <file> --check-index --verbose`
- [ ] Validator exited with code 0 (if code 1: fix errors, re-validate; if code 2: fix TOML syntax, re-validate)
- [ ] No validation errors remain — validator returned exit code 0
- [ ] Temporary descriptor file deleted
- [ ] Summary reported: X primary + Y secondary + Z specialized skills; N excluded candidates

**Do NOT report success until the validator returns exit code 0.**

---

## Using the /pss-setup-agent Command

The simplest way to invoke this entire workflow:

```
/pss-setup-agent /path/to/agent.md
/pss-setup-agent /path/to/agent.md --requirements /path/to/prd.md /path/to/tech-spec.md
/pss-setup-agent plugin-name:agent-name
/pss-setup-agent /path/to/agent.md --output /custom/output.agent.toml
```

This command spawns the `pss-agent-profiler` agent, which follows the full Phase 1-6 workflow above with AI reasoning at every step.

---

## Scoring Reference

See [references/example-and-scoring.md](references/example-and-scoring.md) for the scoring weight table, tier thresholds, troubleshooting guide, and a complete worked example of profiling a React frontend developer agent.

## Instructions

1. **Phase 1 — Gather Requirements**: Read agent `.md` file, identify target domain, languages, frameworks, platforms, and constraints. Complete the Phase 1 checklist.
2. **Phase 2 — Search & Score**: Run the Rust binary in `--agent-profile` mode to score all indexed elements. Use the multi-field index search to find additional candidates. Complete the Phase 2 checklist.
3. **Phase 3 — AI Post-Filtering**: Apply mutual exclusivity, stack compatibility, and redundancy pruning. Remove conflicting, redundant, or off-stack elements. Complete the Phase 3 checklist.
4. **Phase 4 — Cross-Type Coherence**: Verify skill-MCP overlap, agent-command alignment, and rule-agent compatibility. Complete the Phase 4 checklist.
5. **Phase 5 — TOML Assembly**: Assemble the `.agent.toml` with all sections populated, tier assignments justified, and exclusion comments documented. Complete the Phase 5 checklist.
6. **Phase 6 — Validation & Delivery**: Run `pss_validate_agent_toml.py`, fix all errors, deliver the validated file. Complete the Phase 6 checklist.

## Output

The final output is a validated `.agent.toml` file written to `~/.claude/agents/<agent-name>.agent.toml`. The file conforms to the JSON Schema at `${CLAUDE_PLUGIN_ROOT}/schemas/pss-agent-toml-schema.json` and passes `pss_validate_agent_toml.py` with exit code 0.

## Error Handling

- If the Rust binary is not found or not executable, abort with an explicit error message — do not fall back to manual scoring.
- If the skill index (`~/.claude/cache/skill-index.json`) does not exist, instruct the user to run `/pss-reindex-skills` first.
- If validation fails (exit code != 0), fix all errors and re-validate — do not deliver an invalid `.agent.toml`.
- If `CLAUDE_PLUGIN_ROOT` is not set, abort immediately with instructions to set it.

## Examples

See [references/example-and-scoring.md](references/example-and-scoring.md) for a full `.agent.toml` output for a React frontend developer agent, showing all sections populated with reasoned selections and exclusion comments.

## Resources

- **JSON Schema**: `${CLAUDE_PLUGIN_ROOT}/schemas/pss-agent-toml-schema.json`
- **Validator**: `${CLAUDE_PLUGIN_ROOT}/scripts/pss_validate_agent_toml.py`
- **Categories**: `${CLAUDE_PLUGIN_ROOT}/schemas/pss-categories.json` (16 predefined categories)
- **Skill Index**: `~/.claude/cache/skill-index.json`
- **Rust Binary**: `${CLAUDE_PLUGIN_ROOT}/rust/skill-suggester/bin/pss-<platform>`