Create Profile

Create Profile

Create agent profiles — role definitions that scope an agent to a specific domain with explicit constraints and permissions. Profiles are standalone markdown files that define agent roles.

Workflow

1. Gather intent — Understand what the profile should scope. Collect:

   • A short name (lowercase, one word preferred)
   • What domain or responsibility the agent covers
   • What it should and should not touch

2. Investigate the repo — Before asking questions, search for facts that reduce ambiguity:

   • Existing profiles (find where they live in this repo; ask the user if ambiguous)
   • Project structure to understand domain boundaries
   • Existing rules that the profile should reference
   • File patterns that define the scope

   Don't ask the user what you can look up yourself.

3. Clarify — Ask only questions that materially affect the profile:

   • Which files/directories are in scope
   • Which are explicitly out of scope
   • What rules the profile must follow
   • Whether the profile has design authority or just executes

4. Write the profile — Structure:

   # <Name> Agent
   
   One-line role description — domain and boundary.
   
   ## Constraints
   
   - Hard rules this agent must follow
   - Which rules or conventions the profile must follow
   
   ## Scope
   
   What files and actions are in bounds. What is explicitly
   out of bounds. When to stop and hand off.
   
   ## Design Intent
   
   How this agent should approach decisions within its
   domain. What aesthetic or architectural principles guide
   its choices.
   

   Writing principles:

   • Scope is a boundary, not a task list. State what's in and out, not every possible action.
   • Constraints are non-negotiable. If it's a preference, it belongs in Design Intent.
   • Include a stop condition. State when the agent should stop and hand off to a human or another profile.
   • Keep it under 40 lines. A profile is a lens, not a manual.
   • Reference rules, don't repeat them. If a rule covers it, point to it.

5. Validate — Check the profile against the repo:

   • Verify the scope matches actual file structure
   • Confirm no overlap with existing profiles
   • Check that referenced rules exist

6. Confirm — Show the user the created profile and ask if adjustments are needed.

Example Scenario

User: "I want an agent that only handles database migrations and schema changes."

1. Investigates repo — finds migrations/, Flyway config, existing frontend profile for reference
2. Asks: "Should it also handle seed data, or just schema?"
3. Creates database.md profile scoping to migrations/ and schema files, excluding application code
4. Validates — directory exists, no overlap with frontend profile

Example Output

# Database Agent

Manages database migrations and schema changes.

## Constraints

- Follow the git-naming rule for branches and commits
- Never modify application code
- Run migrations in a transaction when supported

## Scope

Modify only:
- `migrations/`
- `schema/`

Do not touch: application code, API handlers, frontend.
If a migration requires application changes, describe
what's needed and stop.

## Design Intent

Prefer reversible migrations. Every up migration has a
corresponding down. Avoid data-destructive operations
without explicit confirmation.

Common Failures

• Scope too broad — "handles backend" is half the repo. Narrow to specific directories or file types.
• Scope too narrow — if the agent can't do useful work within its boundaries, the profile is over-constrained.
• Missing stop condition — without "stop and hand off" guidance, the agent will attempt out-of-scope work rather than flagging it.
• Duplicates a rule — if the constraint applies to all agents, it's a rule, not a profile constraint.

Boundaries

Does:

• Create profile markdown files in the project's profile directory
• Investigate repo structure to define scope
• Reference existing rules

Does not:

• Create skills or rules (use create-skill, create-rule)
• Modify existing profiles without confirmation
• Create profiles for non-agent roles