Skills Configuration Guide

This guide explains how to create and configure skills in Fabric Agent.

What Are Skills?

Skills are specialized instructions that extend Claude's capabilities for specific tasks. They use the exact same SKILL.md format as the Claude Code SDK - making skills fully compatible between systems.

Key points:

• Skills are invoked via slash commands (e.g., /commit, /review-pr)
• Skills can be automatically triggered by file patterns (globs)
• Skills can pre-approve specific tools to run without prompting
• The SKILL.md format is identical to what Claude Code uses internally

Same Format as Claude Code SDK

Fabric Agent uses the identical SKILL.md format as the Claude Code SDK. This means:

1. Format compatibility: Any skill written for Claude Code works in Fabric Agent
2. Same frontmatter fields: name, description, globs, alwaysAllow, requiredSources
3. Same content structure: Markdown body with instructions for Claude

What Fabric Agent adds:

• Visual icons: Display custom icons in the UI for each skill
• Workspace organization: Skills are scoped to workspaces
• UI management: Browse, edit, and validate skills through the interface

Skill Precedence

When a skill is invoked (e.g., /commit):

1. Workspace skill checked first - If ~/.fabric-agent/workspaces/{id}/skills/commit/SKILL.md exists, it's used
2. SDK skill as fallback - If no workspace skill exists, the built-in SDK skill is used

This allows you to:

• Override SDK skills - Create a workspace skill with the same slug to replace built-in behavior
• Extend SDK skills - Reference SDK behavior in your custom skill and add workspace-specific instructions
• Create new skills - Add entirely new skills not in the SDK

Skill Storage

Skills are discovered from three locations, merged at runtime — workspace skills, project-level skills committed to a repo, and SDK fallbacks:

Fabric Agents reads .agents/, .codex/, and .claude/ so repos already using Codex or Claude Code conventions work without changes. Project skills override workspace skills with the same slug; workspace skills override SDK fallbacks. This lets a team commit a workspace-tailored /commit skill that everyone using the repo picks up automatically.

Skill folder layout:

{any-skills-root}/skills/{slug}/
├── SKILL.md          # Required: Skill definition (same format as Claude Code SDK)
├── icon.svg          # Recommended: Skill icon for UI display
├── icon.png          # Alternative: PNG icon
└── (other files)     # Optional: Additional resources

SKILL.md Format

The format is identical to Claude Code SDK skills:

---
name: "Skill Display Name"
description: "Brief description shown in skill list"
globs: ["*.ts", "*.tsx"]     # Optional: file patterns that trigger skill
alwaysAllow: ["Bash"]        # Optional: tools to always allow
requiredSources:             # Optional: sources to auto-enable on invocation
  - linear
---

# Skill Instructions

Your skill content goes here. This is injected into Claude's context
when the skill is active.

## Guidelines

- Specific instructions for Claude
- Best practices to follow
- Things to avoid

## Examples

Show Claude how to perform the task correctly.

Metadata Fields

name (required)

Display name for the skill. Shown in the UI and skill list.

description (required)

Brief description (1-2 sentences) explaining what the skill does.

globs (optional)

Array of glob patterns. When a file matching these patterns is being worked on, the skill may be automatically suggested or activated.

globs:
  - "*.test.ts"           # Test files
  - "*.spec.tsx"          # React test files
  - "**/__tests__/**"     # Test directories

alwaysAllow (optional)

Array of tool names that are automatically allowed when this skill is active. Useful for skills that require specific tools without prompting.

alwaysAllow:
  - "Bash"                # Allow bash commands
  - "Write"               # Allow file writes

requiredSources (optional)

Array of source slugs to auto-enable when this skill is invoked. When a user mentions the skill, the listed sources are enabled for the session before the agent starts — so tools from those sources are available from the first turn.

Sources must exist in the workspace and be authenticated. Unauthenticated or missing sources are silently skipped (the existing runtime auto-enable handles them as a fallback).

requiredSources:
  - linear               # Auto-enable Linear source
  - github               # Auto-enable GitHub source

Creating a Skill

1. Create the skill directory

mkdir -p ~/.fabric-agent/workspaces/{ws}/skills/my-skill

2. Write SKILL.md

---
name: "Code Review"
description: "Review code changes for quality, security, and best practices"
globs: ["*.ts", "*.tsx", "*.js", "*.jsx"]
---

# Code Review Skill

When reviewing code, focus on:

## Quality Checks
- Consistent code style
- Clear naming conventions
- Appropriate abstractions

## Security Checks
- Input validation
- Authentication/authorization
- Sensitive data handling

## Best Practices
- Error handling
- Performance considerations
- Test coverage

3. Add an icon (IMPORTANT)

Every skill should have a visually relevant icon. This helps users quickly identify skills in the UI.

Icon requirements:

• Filename: Must be icon.svg, icon.png, icon.jpg, or icon.jpeg
• Format: SVG preferred (scalable, crisp at all sizes)
• Size: For PNG/JPG, use at least 64x64 pixels

How to get an icon:

1. Search online icon libraries:

   • Heroicons - MIT licensed
   • Feather Icons - MIT licensed
   • Simple Icons - Brand icons (git, npm, etc.)

2. Use WebFetch to download:

   # Find an appropriate icon URL and download it
   WebFetch to get SVG content, then save to icon.svg

3. Match the skill's purpose:

   • Git/commit skill → git icon or commit icon
   • Test skill → checkmark or test tube icon
   • Deploy skill → rocket or cloud icon
   • Review skill → magnifying glass or eye icon

4. Validate the skill

IMPORTANT: Always validate after creating or editing a skill:

skill_validate({ skillSlug: "my-skill" })

This validates:

• Slug format (lowercase, alphanumeric, hyphens only)
• SKILL.md exists and is readable
• YAML frontmatter is valid
• Required fields present (name, description)
• Content is non-empty
• Icon format (if present)

Example Skills

Commit Message Skill

---
name: "Commit"
description: "Create well-formatted git commit messages"
alwaysAllow: ["Bash"]
---

# Commit Message Guidelines

When creating commits:

1. **Format**: Use conventional commits
   - `feat:` New feature
   - `fix:` Bug fix
   - `docs:` Documentation
   - `refactor:` Code refactoring
   - `test:` Adding tests

2. **Style**:
   - Keep subject line under 72 characters
   - Use imperative mood ("Add feature" not "Added feature")
   - Explain why, not what (the diff shows what)

3. **Co-authorship**:
   Always include: `Co-Authored-By: Claude <noreply@anthropic.com>`

Recommended icon: Git commit icon from Heroicons or Simple Icons

Team Standards Skill

---
name: "Team Standards"
description: "Enforce team coding conventions and patterns"
globs: ["src/**/*.ts", "src/**/*.tsx"]
---

# Team Coding Standards

## File Organization
- One component per file
- Co-locate tests with source files
- Use barrel exports (index.ts)

## Naming Conventions
- Components: PascalCase
- Hooks: camelCase with `use` prefix
- Constants: SCREAMING_SNAKE_CASE

## Import Order
1. External packages
2. Internal packages (@company/*)
3. Relative imports

Recommended icon: Clipboard list or checklist icon

Skill with Required Sources

---
name: "Linear Triage"
description: "Triage and prioritize Linear issues"
requiredSources:
  - linear
---

# Linear Triage

When triaging issues:
1. List unassigned issues from the current sprint
2. Categorize by severity
3. Suggest assignees based on expertise

Recommended icon: Kanban board or list icon

When this skill is invoked, the linear source is automatically enabled for the session — no manual toggle needed.

Overriding SDK Skills

To customize a built-in SDK skill like /commit:

1. Create ~/.fabric-agent/workspaces/{ws}/skills/commit/SKILL.md
2. Write your custom instructions
3. Add an icon
4. Run skill_validate({ skillSlug: "commit" })

Your skill will be used instead of the SDK's built-in version.

This is useful for:

• Adding team-specific commit message formats
• Enforcing project-specific coding standards
• Customizing review criteria for your codebase

Skills panel

Open the Skills sidebar entry to browse every skill available to the active session. The panel surfaces:

• Search — fuzzy match across skill name, description, and source.
• Source badges — visual indicator of where the skill came from (workspace, project .agents, project .codex, project .claude, global, or SDK fallback). Click a badge to filter to skills from that source.
• Grouping — group by source or by workspace to see what each scope contributes.
• Filtering — narrow by enabled/disabled, by required-source dependency, or by glob pattern.

Selecting a skill opens its detail page — slug, frontmatter, source path, full instructions, and the icon. From there you can edit the SKILL.md inline or open the file in your editor.

Best Practices

1. Be specific: Give Claude clear, actionable instructions
2. Include examples: Show the expected output format
3. Set boundaries: Explain what NOT to do
4. Keep focused: One skill = one specific task or domain
5. Add a relevant icon: Makes skills easily identifiable in the UI
6. Always validate: Run skill_validate after creating or editing
7. Commit team skills to .agents/skills/: Repo-tracked skills propagate without per-developer setup.

Troubleshooting

Skill not loading:

• Check slug format (lowercase, alphanumeric, hyphens only)
• Verify SKILL.md exists and is readable
• Run skill_validate for detailed errors

Skill not triggering:

• Check glob patterns match your files
• Verify skill is in correct workspace

Icon not showing:

• Use supported formats: svg, png, jpg, jpeg
• File must be named icon.{ext} (not my-icon.svg)
• Check icon file is not corrupted
• For SVG, ensure valid XML structure