Skip to content

Customization

How to customize agentic for individual projects without modifying the shared library.

Local Profile

When you deploy a profile, a copy is saved to .agentic/profile.yaml. This is your project's own configuration that you can edit freely.

If you want to start from scratch without a predefined profile, scaffold the local agentic workspace first:

agentic init

This creates .agentic/config.yaml, .agentic/profile.yaml, .agentic/mcp.yaml, .agentic/providers.yaml, .agentic/agents.yaml, and .agentic/project-skills/.

What You Can Customize

  • Add or remove fragments
  • Add or remove skills (including project: prefixed skills)
  • Modify tech_stack (languages, frameworks, proprietary libraries)
  • Change build/test/lint commands
  • Adjust tier configuration (for nested projects)

Regenerating After Changes

After editing .agentic/profile.yaml, regenerate your project:

agentic sync

This re-runs compose with your local profile, regenerates vendor files, and preserves your active vendors.

Providers Configuration

Optional provider preferences live in .agentic/providers.yaml:

# yaml-language-server: $schema=https://raw.githubusercontent.com/soulcodex/agentic/main/schemas/providers.schema.json
version: "1"
default_provider: "claude"
providers:
  claude:
    enabled: true
  cursor:
    enabled: true

Behavior:

  • If .agentic/providers.yaml is missing, default provider behavior applies.
  • If present but invalid, agentic compose and agentic sync fail with a clear error.
  • This file influences runtime pivot preferences only; AGENTS.md remains canonical.
  • Cursor provider/model mapping is intentionally unsupported until Cursor publishes an official project-local contract for that configuration surface.

MCP Configuration (Pivot Model)

Project MCP declarations live in .agentic/mcp.yaml:

# yaml-language-server: $schema=https://raw.githubusercontent.com/soulcodex/agentic/main/schemas/mcp.schema.json
strategy: merge
servers:
  github:
    type: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]

agentic sync and agentic compose seed vendor MCP outputs from this file:

  • .mcp.json (Claude shape)
  • opencode.json (mcp block translation)
  • .gemini/settings.json (mcpServers translation)
  • .cursor/mcp.json (mcpServers translation)
  • existing opencode.json, if present in the project (mcp block translation)

If .agentic/mcp.yaml is missing, MCP outputs are not seeded.

Project-Local Skills

For skills specific to a single project that shouldn't live in the shared library, create them in .agentic/project-skills/:

mkdir -p .agentic/project-skills/my-custom-workflow

Create .agentic/project-skills/my-custom-workflow/SKILL.md:

---
name: my-custom-workflow
description: >
  Project-specific deployment workflow for this repo.
version: 1.0.0
tags: [deployment, internal]
resources: []
vendor_support:
  claude: native
  opencode: native
  copilot: prompt-inject
  codex: prompt-inject
  gemini: prompt-inject
---

## Steps

1. Run pre-deploy checks: `make verify`
2. Build the artifact: `make build`
3. Deploy to staging: `make deploy-staging`
4. Run smoke tests: `make smoke-test`

Reference it in your profile:

# In .agentic/profile.yaml
skills:
  - code-review                    # from library
  - project:my-custom-workflow     # from .agentic/project-skills/

Or deploy with it directly:

agentic deploy <profile> [target] <vendors> --skills project:my-custom-workflow

Project skills are copied to .agentic/skills/ alongside library skills and symlinked to vendor-specific paths just like regular skills.

Example: Use a Library Skill for Parallel Branch Work

Enable the shared git-worktree-workspaces skill in your local profile:

# In .agentic/profile.yaml
skills:
  - git-worktree-workspaces
  - git-flow-pr

Then regenerate:

agentic sync

Declare Proprietary Libraries

List internal packages that agents need to be aware of. Agents are told to load the relevant documentation before making changes to code that uses these packages.

Project-wide

Declared in tech_stack in .agentic/profile.yaml — appears in the root AGENTS.md:

tech_stack:
  proprietary_libraries:
    - name: "@acme/core"
      description: "Core domain primitives shared across all services"
      url_doc: "https://docs.acme.internal/core"   # optional

Tier-specific (nested profiles only)

Declared under the relevant tier — appears in that tier's AGENTS.md:

tiers:
  backend:
    proprietary_libraries:
      - name: "@acme/domain-kit"
        description: "Backend domain helpers"
        url_doc: "https://docs.acme.internal/domain-kit"

url_doc is optional. When omitted the Docs column in AGENTS.md shows —.

Add Custom Markdown Context Index

If your project has critical markdown documents agents should read first, declare them in: output.custom_index.element[] inside .agentic/profile.yaml.

output:
  custom_index:
    title: "Project Knowledge Base"
    description: "Read these docs before changing architecture, infra, or release workflow."
    element:
      - path: "docs/architecture.md"
        why: "Defines bounded contexts and dependency rules."
        when: "Before touching domain or service boundaries."
      - path: "docs/runbooks/release.md"
        why: "Contains release gates and rollback procedure."
        when: "Before CI/CD or versioning changes."

Then run:

agentic sync

This adds a dedicated markdown context table to generated AGENTS.md.

When to Use What

Need Solution
Customize one project Edit .agentic/profile.yaml, run agentic sync
Reusable skill for one project Create in .agentic/project-skills/ (see above)
Shared across all projects Add to library (see Contributing guide)

What to Commit to Your Project Repo

agentic automatically injects a managed .gitignore block on every deploy or sync so you never have to figure this out manually. The block is delimited by # agentic:start / # agentic:end and is updated in-place on re-runs.

What goes in and what stays out depends on whether you deployed with --link or not.

Copy mode (default)

.agentic/skills/, .agentic/fragments/, and .agentic/vendor-files/ contain real files copied from the library. They are committed to the repo so the project is self-contained and cloneable without the library installed on every machine.

Those same directories are symlinks pointing to the library on the deploying machine. Committing a symlink to an absolute local path breaks every other machine, so they are gitignored automatically. This behavior applies to both standalone and nested profiles.

What this means for your repo

Path Copy mode Link mode Why
AGENTS.md ✅ commit ✅ commit Source of truth — review in PRs
.agentic/config.yaml ✅ commit ✅ commit Reproducibility anchor
.agentic/profile.yaml ✅ commit ✅ commit Per-project customization
.agentic/mcp.yaml ✅ commit ✅ commit MCP source-of-truth for seeding
.agentic/project-skills/ ✅ commit ✅ commit Your code — treat as source
.agentic/skills/ ✅ commit 🚫 ignore Real files vs symlink to library
.agentic/fragments/ ✅ commit 🚫 ignore Real files vs symlink to library
.agentic/vendor-files/ ✅ commit 🚫 ignore Real files vs symlink to library
CLAUDE.md, GEMINI.md, vendor symlinks 🚫 ignore 🚫 ignore Always recreated by agentic sync / agentic switch

Action required: do not commit vendor entry-point files.

Files like CLAUDE.md, .github/copilot-instructions.md, .gemini/system.md, and .cursor/rules are regenerated by agentic sync / agentic switch and are always gitignored in both copy and link modes.

Cursor switch safety guarantees

agentic switch cursor reads .agentic/vendor-files/cursor/switch-manifest.json and manages every declared rules path (for example .cursor/rules, backend/.cursor/rules, ui/.cursor/rules).

  • If a managed path already exists as a real directory, agentic migrates it to <path>.backup (then <path>.backup.N on collisions) before linking.
  • If activation fails after mutations begin, agentic restores prior symlink/config state and rolls back migrated Cursor rules paths.

Switching between modes

Switching copy → link mode (stop carrying library files in your repo):

  1. Set link mode in config:
  2. for new projects: agentic init --link
  3. for existing projects: set .agentic/config.yaml deploy_mode: link
  4. Regenerate in link mode with agentic sync (or re-run deploy with --link)
  5. Remove the now-symlinked directories from git's index: 
    git rm -r --cached .agentic/skills .agentic/fragments .agentic/vendor-files
git commit -m "chore: switch agentic to link mode"
  6. The managed .gitignore block is updated automatically — the three paths are added to it.

Switching link → copy mode (make the project fully self-contained):

  1. Re-deploy without --link: update deploy_mode in .agentic/config.yaml to copy then run agentic sync
  2. Stage the newly materialized directories: 
    git add .agentic/skills .agentic/fragments .agentic/vendor-files
git commit -m "chore: switch agentic to copy mode"
  3. The managed .gitignore block is updated automatically — the three paths are removed from it.

Config Lock File

Every agentic deploy or agentic compose writes TARGET/.agentic/config.yaml:

# Managed by agentic library — do not edit manually
library_commit: "abc123..."
profile: "golang-hexagonal-cobra-cli"
profile_version: "1.0.0"
composed_at: "2026-03-03T12:00:00Z"
mode: lean
agentic_root: "/Users/you/agentic"
active_vendors:
  - claude
  - copilot
structure: nested          # only for nested profiles
tiers: [backend, ui]       # only for nested profiles

The agentic_root and active_vendors fields enable the global CLI to work from any directory within your project.