Creating new skills

Instead of repeating the same prompts or instructions in every conversation, create a skill that Faheem Code can load automatically when needed. Skills transform one-time prompts into reusable, maintainable knowledge that improves over time.

Why create skills?

Before (repeating yourself):

Please analyze this code using our company's Python style guide:
- Use black for formatting
- Max line length 88
- Use type hints for all functions
- Follow PEP 8 naming conventions
...

After (using a skill):

Review this Python code

The skill triggers automatically and applies all your style guidelines consistently.

When to create a skill

Create a skill when you find yourself:

Repeating the same instructions across multiple conversations
Working with domain-specific knowledge (company policies, API schemas, workflows)
Using the same multi-step procedures repeatedly
Needing consistent behavior for specific tools or frameworks
Sharing best practices across a team

Quick start

Automated approach: let Faheem Code help

To create a skill with guided assistance, ask Faheem Code to help you:

Create a skill for [your use case]

or simply:

Write a new skill

The skill-creator skill (from the Faheem Code public skills library) will guide you through an interactive process:

Asks questions about your use cases and requirements
Suggests appropriate skill structure (references, scripts, assets)
Helps you write effective trigger keywords and descriptions
Ensures you follow best practices automatically
Creates the complete skill structure for you

This is the recommended approach, especially when you're starting out.

Manual approach

If you prefer to create the skill structure manually:

Create the skill directory:
```
mkdir -p .agents/skills/my-skill
```
Create the SKILL.md file:
```
touch .agents/skills/my-skill/SKILL.md
```
Add content (see structure and guidelines below)
Test it by using a trigger keyword in your prompt

Determining scope

Before writing your skill, define its scope clearly:

Ask these questions

What specific task does this skill handle?
- ❌ Too broad: "Help with coding"
- ✅ Focused: "Lint Python code using ruff with our company rules"
What knowledge is required?
- Code style guidelines
- API documentation
- Domain-specific schemas
- Multi-step procedures
What resources are needed?
- Scripts for deterministic tasks
- Reference documents for detailed information
- Asset files for templates or boilerplate
Who will use this skill?
- Just you (keep it simple)
- Your team (add more documentation)
- Public sharing (comprehensive examples)

Scope examples

Good scope (focused):

"Configure pre-commit hooks for Python projects"
"Generate financial reports using our SQL schema"
"Deploy to our Kubernetes staging environment"

Poor scope (too broad):

"Help with Python"
"Work with databases"
"Deploy applications"

Choosing name and triggers

The skill name and trigger keywords determine when Faheem Code loads your skill.

Naming your skill

Choose a clear, descriptive name:

Use lowercase with hyphens: python-linting, k8s-deploy, api-docs
Be specific: ruff-linter not just linter
Match common terms: Use vocabulary your users know

Defining triggers

Triggers are keywords that automatically activate your skill. Choose words users naturally say when they need this skill.

Keyword triggers

List specific words or phrases that should activate the skill:

---
name: python-linting
description: This skill should be used when the user asks to "lint Python code", "check Python style", "run ruff", or mentions Python code quality.
triggers:
- lint
- linting
- ruff
- code quality
---

Best practices:

Include 2-5 trigger keywords
Use terms users actually say
Include tool names (e.g., "ruff", "pytest")
Include action words (e.g., "lint", "test", "deploy")

Description-based triggering

The skill description is crucial for trigger matching. Write it in third person and include specific phrases:

description: This skill should be used when the user asks to "deploy to Kubernetes", "apply K8s manifests", "check pod status", or mentions kubectl commands. Provides comprehensive Kubernetes deployment workflows.

Key elements:

Start with "This skill should be used when..."
Quote specific user phrases: "deploy to Kubernetes"
List concrete scenarios
Mention related tools or frameworks

Path triggers (rules)

Instead of keywords, scope a skill to files with a paths: glob. The skill becomes a path-triggered rule that Faheem Code injects automatically whenever the agent reads, edits, or creates a matching file — no keyword or model decision needed:

---
name: api-validation
paths:
  - "src/api/**/*.ts"
  - "**/*.route.ts"
---

When to use:

Conventions tied to specific files (e.g. "validate request inputs with zod" for API routes)
Guidance you want applied deterministically, without relying on trigger words
paths: takes precedence over triggers: if a file declares both

Examples of good triggers

# API integration skill
triggers:
- stripe
- payment
- checkout

# Database skill
triggers:
- bigquery
- sql query
- data warehouse

# Deployment skill
triggers:
- deploy
- kubernetes
- k8s
- kubectl

Defining the skill body

The skill body contains the instructions Faheem Code will follow. Write in imperative form (command form) rather than second person.

Basic structure

---
name: skill-name
description: This skill should be used when...
triggers:
- keyword1
- keyword2
---

# Skill Title

Brief overview of what this skill does.

## Core Instructions

Main procedures and guidelines.

## Common Patterns

Typical use cases and solutions.

## Additional Resources

(Optional) References to bundled files.

Writing style

Use imperative/infinitive form: ✅ "Check the configuration file" ✅ "Validate input before processing" ✅ "Run tests after deployment"

Avoid second person: ❌ "You should check the configuration" ❌ "You need to validate input" ❌ "You must run tests"

Keep it focused

SKILL.md content:

Core concepts and workflows (1,500-2,000 words ideal)
Essential procedures
Quick reference information
Pointers to additional resources

What NOT to include:

Exhaustive API documentation (use references/ instead)
Detailed edge cases (use references/ instead)
Long examples (use references/ instead)

Best practices and tips

Use numbered step workflows

For multi-step procedures, use numbered lists:

## Deployment Workflow

1. **Validate the configuration**:
   ```bash
   kubectl apply --dry-run=client -f deployment.yaml

Apply to staging:

kubectl apply -f deployment.yaml -n staging

Verify pod status:
```
kubectl get pods -n staging --watch
```

Check logs:

kubectl logs -f deployment/app-name -n staging

**Benefits:**
- Clear sequence for complex workflows
- Easy to follow and verify
- Reduces errors from skipped steps

### Add large files as references

Keep SKILL.md lean by moving detailed content to `references/`:

my-skill/ ├── SKILL.md # Core instructions (< 3,000 words) └── references/ ├── api-docs.md # Detailed API reference ├── examples.md # Comprehensive examples └── troubleshooting.md # Edge cases and fixes

**In SKILL.md, reference these files:**

```markdown
## Additional Resources

For detailed information, see:
- **`references/api-docs.md`** - Complete API documentation
- **`references/examples.md`** - Working code examples
- **`references/troubleshooting.md`** - Common issues and solutions

Benefits:

Keeps context window smaller when skill loads
Faheem Code reads references only when needed
Easier to maintain and update specific sections

Create scripts for predictable steps

For tasks that are repeatedly rewritten or need deterministic behavior, create executable scripts:

my-skill/
├── SKILL.md
└── scripts/
    ├── validate_config.py
    ├── deploy.sh
    └── rollback.sh

When to use scripts:

Same code being rewritten repeatedly
Deterministic reliability required
Complex parsing or validation
Multi-step automation

Reference scripts in SKILL.md:

## Validation

Run the validation script:

\`\`\`bash
python3 scripts/validate_config.py config.yaml
\`\`\`

This checks:
- YAML syntax
- Required fields
- Value constraints

Benefits:

Token efficient (scripts can run without being read)
Deterministic behavior
Reusable across projects
Can be versioned and tested

Include quick reference tables

Use tables for configuration options, command flags, or status codes:

## Configuration Options

| Option | Default | Description |
|--------|---------|-------------|
| `timeout` | 30s | Maximum wait time |
| `retries` | 3 | Number of retry attempts |
| `env` | production | Target environment |

Provide concrete examples

Show real examples, not abstract descriptions:

## Example Usage

Deploy the web application:

\`\`\`bash
# Build the image
docker build -t myapp:v1.0 .

# Push to registry
docker push registry.example.com/myapp:v1.0

# Update Kubernetes deployment
kubectl set image deployment/web web=registry.example.com/myapp:v1.0
\`\`\`

Use progressive disclosure

Structure information from simple to complex:

SKILL.md: Essential workflows and core concepts
references/: Detailed patterns, advanced techniques, edge cases
scripts/: Automation for predictable tasks
assets/: Templates and boilerplate files

Complete example

Here's a complete skill for Python code review:

python-review/
├── SKILL.md
├── references/
│   ├── style-guide.md
│   └── common-issues.md
└── scripts/
    └── run-checks.sh

SKILL.md:

---
name: python-review
description: This skill should be used when the user asks to "review Python code", "check Python style", "lint Python", or requests code quality analysis. Provides comprehensive Python code review workflows.
triggers:
- python review
- code review
- lint python
- black
- ruff
---

# Python Code Review

Review Python code using company standards and best practices.

## Review Workflow

1. **Run automated checks**:
   \`\`\`bash
   scripts/run-checks.sh
   \`\`\`

2. **Review linter output** for:
   - Style violations (Black, Ruff)
   - Type errors (mypy)
   - Security issues (bandit)

3. **Check code structure**:
   - Function length (< 50 lines)
   - Complexity (< 10 cyclomatic)
   - Naming conventions

4. **Verify tests**:
   \`\`\`bash
   pytest tests/ --cov=src --cov-report=term
   \`\`\`

## Style Guidelines

- **Formatting**: Black with 88-character line limit
- **Linting**: Ruff with company config
- **Types**: Full type hints for public APIs
- **Docstrings**: Google style for all public functions

## Additional Resources

- **`references/style-guide.md`** - Complete style guide
- **`references/common-issues.md`** - Common mistakes and fixes
- **`scripts/run-checks.sh`** - Automated quality checks

Testing your skill

After creating your skill:

Verify structure:
```
ls .agents/skills/your-skill/SKILL.md
```
Check frontmatter: Ensure YAML is valid with name, description, and triggers
Test trigger keywords: Use a trigger word in a prompt:
```
Help me lint this Python code
```
Verify loading: Faheem Code should indicate the skill was loaded
Iterate: Improve based on actual usage

Common mistakes to avoid

Next steps

Add your skill to your workspace
Monitor skill performance in production
Share skills with the community
Learn the AgentSkills format for advanced features
Explore example skills for inspiration

Why create skills?​

When to create a skill​

Quick start​

Automated approach: let Faheem Code help​

Manual approach​

Determining scope​

Ask these questions​

Scope examples​

Choosing name and triggers​

Naming your skill​

Defining triggers​

Examples of good triggers​

Defining the skill body​

Basic structure​

Writing style​

Keep it focused​

Best practices and tips​

Use numbered step workflows​

Create scripts for predictable steps​

Include quick reference tables​

Provide concrete examples​

Use progressive disclosure​

Complete example​

Testing your skill​

Common mistakes to avoid​

Next steps​

Further reading​