Organization and user skills

Usage

These skills can be any type of skill and will be loaded accordingly. However, they are applied to all repositories belonging to the organization or user.

Add a .agents repository under the organization or user and create a skills directory and place the skills in that directory.

For GitLab organizations, use faheem-code-config as the repository name instead of .agents, since GitLab doesn't support repository names starting with non-alphanumeric characters.

Example

General skill file example for organization Great-Co located inside the .agents repository: skills/org-skill.md:

* Use type hints and error boundaries; validate inputs at system boundaries and fail with meaningful error messages.
* Document interfaces and public APIs; use implementation comments only for non-obvious logic.
* Follow the same naming convention for variables, classes, constants, etc. already used in each repository.

For GitLab organizations, the same skill would be located inside the faheem-code-config repository.

User skills when running Faheem Code on your own

When running Faheem Code on your own, you can place skills in the ~/.agents/skills/ folder on your local system and Faheem Code will always load them for all your conversations. Repo-level overrides live in .agents/skills/.

User skills from ~/.agents/skills/ are loaded automatically — no extra configuration needed.

When running Faheem Code via Docker, the agent-server container cannot see your host filesystem by default. You need to mount your local skills directory into the sandbox using the SANDBOX_VOLUMES environment variable:

docker run -it --rm --pull=always \
  -e SANDBOX_VOLUMES="$HOME/.agents/skills:/home/faheemcode/.agents/skills:ro" \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/smart-national-solution/faheem-code-agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.faheem-code:/.faheem-code \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name faheem-code-app \
  ghcr.io/smart-national-solution/faheem-code-app:1.8

Warning

Mount into ~/.agents/skills inside the container (not ~/.faheem-code/skills). Mounting into ~/.faheem-code/skills would overwrite the public skills cache and prevent built-in skills from loading.

You can store your skills in any host directory (e.g., ~/my-skills/) and mount them to ~/.agents/skills in the sandbox:

-e SANDBOX_VOLUMES="$HOME/my-skills:/home/faheemcode/.agents/skills:ro"

If you also need to mount a workspace, use a comma-separated list:

-e SANDBOX_VOLUMES="$HOME/project:/workspace:rw,$HOME/.agents/skills:/home/faheemcode/.agents/skills:ro"

See the SANDBOX_VOLUMES documentation for more details on the mount format.