wiki-skills

# Agent Coding Guide for wiki-skills

This repository contains Agent Skills for AI coding agents following the [Agent Skills specification](https://agentskills.io/). Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools for Wikimedia projects.

## What Skills Provide

Think of skills as "onboarding guides" for specific domains or tasks—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess.

1. **Specialized workflows** - Multi-step procedures for Wikipedia, Wikidata, MediaWiki, etc.
2. **Tool integrations** - Instructions for working with Wikimedia APIs and formats
3. **Domain expertise** - Wikimedia-specific knowledge, schemas, policies
4. **Bundled resources** - Scripts, references, and assets for complex and repetitive tasks

## Project Overview

**Type**: Agent Skills Repository (documentation, not compiled code)
**Technologies**: Markdown + YAML frontmatter, optional bundled resources
**Repository**: https://gitlab.wikimedia.org/santhosh/wiki-skills
**Distribution**: Via `npx skills add <repo-url>`

## Build/Test Commands

**No traditional build system** - this is a documentation project with no compilation step.

### Validation Commands

```bash
# No Python scripts currently available in this repository
# If adding validation scripts, they would go in a top-level scripts/ directory
# Example: python scripts/package_skill.py <path/to/skill-folder>
```

### Git Commands

```bash
# Standard git workflow
git status                    # Check repository status
git log --oneline            # View commit history
git add <files>              # Stage changes
git commit -m "message"      # Commit changes
git push origin master       # Push to GitLab
```

## Repository Structure

```
wiki-skills/
├── README.md                           # Installation and usage guide
└── skills/                             # Individual skill packages
    ├── codex-design-tokens/            # Wikimedia Codex design tokens (444 lines)
    │   ├── SKILL.md                    # Main instructions
    │   ├── references/                 # Supporting documentation (loaded on-demand)
    │   └── assets/                     # Template files for output (not in context)
    ├── mediawiki-database-tables/      # MediaWiki DB schema (732 lines)
    ├── wikidata-natural-query/         # Wikidata queries (798 lines)
    ├── wikipedia-editor-research/      # Wikipedia drafting (171 lines)
    ├── wikipedia-rest-api/             # Wikipedia API guide (397 lines)
    └── wikimedia-gerrit/               # Wikimedia Gerrit code review (412 lines)
        ├── SKILL.md                    # Main instructions
        └── references/                 # Workflow documentation
```

## Anatomy of a Skill

Every skill consists of a required SKILL.md file and optional bundled resources:

```
skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts)
```

### SKILL.md (required)

Main instruction file with two parts:

1. **YAML Frontmatter** (at top of file):
```yaml
---
name: skill-name-in-kebab-case
description: Third-person description of what the skill does. This skill should be used when...
---
```

2. **Markdown Body** - Instructions for AI agents (<5,000 words recommended)

**Metadata Quality:** The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it.

### Bundled Resources (optional)

#### Scripts (`scripts/`)

Executable code for tasks that require deterministic reliability or are repeatedly rewritten.

- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
- **Benefits**: Token efficient, deterministic, may be executed without loading into context
- **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments

#### References (`references/`)

Documentation and reference material intended to be loaded as needed into context to inform Claude's process.

- **When to include**: For documentation that Claude should reference while working
- **Examples**: Database schemas, API documentation, domain knowledge, company policies
- **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed
- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill.

#### Assets (`assets/`)

Files not intended to be loaded into context, but rather used within the output Claude produces.

- **When to include**: When the skill needs files that will be used in the final output
- **Examples**: Brand assets, PowerPoint templates, HTML/React boilerplate, fonts
- **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context

## Code Style Guidelines

### Documentation Writing Style

**CRITICAL**: Use imperative/infinitive form (verb-first), NOT second person:

✅ **Correct**:
- "To accomplish X, do Y"
- "Use tokens for styling"
- "Apply the following pattern"
- "When handling queries, follow this workflow"

❌ **Incorrect**:
- "You should accomplish X"
- "You can use tokens"
- "You will apply the pattern"

### YAML Frontmatter Rules

1. **name**: Required, lowercase-with-hyphens format
2. **description**: Required, third-person perspective explaining when to use the skill
   - Start with action verbs or capability descriptions
   - Include trigger conditions: "This skill should be used when..."
   - Example: "Acts as an experienced Wikipedia editor to research, structure, and draft..."

### Content Organization

1. **Keep SKILL.md lean** (<5,000 words recommended)
   - Core instructions and workflows only
   - Move detailed references to `references/` directory
   - Avoid duplication between SKILL.md and reference files
   - Information should live in either SKILL.md or references, not both

2. **Progressive Disclosure Design** (three-tier loading):
   - Level 1: Metadata (name + description) - always in context (~100 words)
   - Level 2: SKILL.md body - loaded when skill triggered (<5k words)
   - Level 3: References/assets - loaded as needed (unlimited*)

   *Unlimited because scripts can be executed without reading into context window.

3. **Reference Files** (when >10k words):
   - Include grep search patterns at the top for discoverability
   - Example: `<!-- grep: "P31", "instance of", "wdt:P31" -->`
   - Helps agents quickly locate specific content

### Section Structure

Typical SKILL.md sections (in order):

```markdown
---
name: skill-name
description: Description here
---

# Skill Title

## Overview / Introduction
Brief explanation of what the skill does

## When to Use This Skill
Bullet list of trigger scenarios

## Core Principles / Workflows
Main operational guidelines

## Instructions for the Agent
Detailed step-by-step instructions

## Examples
Concrete usage examples with inputs and outputs

## Reference Materials (optional)
Links to bundled references or external docs
```

### Formatting Conventions

1. **Headers**: Use ATX-style headers (`#`, `##`, `###`)
2. **Code blocks**: Always specify language for syntax highlighting
3. **Tables**: Use GitHub-flavored Markdown tables for structured data
4. **Lists**: Use `-` for unordered lists, `1.` for ordered lists
5. **Emphasis**: Use `**bold**` for emphasis, `*italic*` sparingly, `` `code` `` for technical terms

### Technical Writing Guidelines

1. **Be objective and instructional** - skills are tools, not conversational agents
2. **Use active voice** - "Use the API" not "The API can be used"
3. **Be specific** - provide exact commands, patterns, and examples
4. **Include error handling** - document failure modes and recovery steps
5. **Provide context** - explain why certain approaches are recommended

## File Naming Conventions

- **Skills**: `kebab-case-names/`
- **Markdown files**: `SKILL.md` (always uppercase), `README.md` (uppercase)
- **Reference files**: `kebab-case-name.md` in `references/`
- **Assets**: Descriptive names in `assets/`, e.g., `basic-page.html`, `component-template.html`

## Git Commit Guidelines

Based on repository history, use simple, descriptive commit messages:

```bash
# Good commit messages (imperative mood):
"Add skill-creator skill"
"Remove invalid --spacing-100"
"Update API endpoint documentation"
"Fix typo in wikidata-natural-query"

# Structure for larger changes:
"[skill-name] Brief description of change"
```

- Use imperative mood ("Add", "Fix", "Update", not "Added", "Fixed")
- Keep first line under 72 characters
- Reference issues when applicable
- No need for elaborate multi-paragraph commits for documentation changes

## Common Workflows

### Creating a New Skill

Follow the "Skill Creation Process" in order, skipping steps only if there is a clear reason why they are not applicable.

#### Step 1: Understanding the Skill with Concrete Examples

Clearly understand concrete examples of how the skill will be used. Ask questions like:
- "What functionality should the skill support?"
- "Can you give some examples of how this skill would be used?"
- "What would a user say that should trigger this skill?"

Example questions for an image-editor skill:
- "What functionality should the image-editor skill support? Editing, rotating, anything else?"
- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"

#### Step 2: Planning the Reusable Skill Contents

Analyze each concrete example to identify what scripts, references, and assets would be helpful:

- **Scripts example**: For a `pdf-editor` skill handling "Help me rotate this PDF", create `scripts/rotate_pdf.py` to avoid rewriting rotation code each time
- **Assets example**: For a `frontend-webapp-builder` skill, create `assets/hello-world/` template with boilerplate HTML/React files
- **References example**: For a `big-query` skill, create `references/schema.md` documenting table schemas and relationships

#### Step 3: Create the Skill Directory

Create the skill directory structure:

```bash
mkdir -p skills/new-skill-name
cd skills/new-skill-name
```

Create `SKILL.md` with proper frontmatter:

```yaml
---
name: skill-name-in-kebab-case
description: Third-person description. This skill should be used when...
---

# Skill Title

[Content here...]
```

Create optional resource directories as needed:
```bash
mkdir -p scripts references assets
```

#### Step 4: Edit the Skill

Focus on including information that would be beneficial and non-obvious to another instance of Claude.

**Start with Reusable Skill Contents:**
1. Implement the `scripts/`, `references/`, and `assets/` files identified in Step 2
2. May require user input (e.g., brand assets, documentation)

**Update SKILL.md:**

Answer these questions in the skill:
1. What is the purpose of the skill, in a few sentences?
2. When should the skill be used?
3. In practice, how should Claude use the skill? Reference all reusable skill contents.

**Writing Style:** Write the entire skill using **imperative/infinitive form** (verb-first instructions), not second person. Use objective, instructional language (e.g., "To accomplish X, do Y" rather than "You should do X").

#### Step 5: Test and Iterate

1. Test the skill on real tasks
2. Notice struggles or inefficiencies
3. Identify how SKILL.md or bundled resources should be updated
4. Implement changes and test again

### Modifying Existing Skills

1. Read the entire SKILL.md first
2. Maintain consistent voice and structure
3. Keep changes focused and atomic
4. Update description if trigger conditions change
5. Don't duplicate content between SKILL.md and references

### Adding Reference Materials

1. Place in `references/` subdirectory
2. Use descriptive kebab-case filenames
3. Add grep patterns at top if >10k words
4. Reference from SKILL.md when appropriate

## Quality Standards

- **Accuracy**: All technical information must be correct and up-to-date
- **Completeness**: Include all necessary context for agents to succeed
- **Clarity**: Use simple, direct language; avoid jargon when possible
- **Consistency**: Follow established patterns across all skills
- **Testability**: Provide examples that can be validated

## Best Practices

1. **Start with the description** - it determines when skills are triggered
2. **Use examples liberally** - show, don't just tell
3. **Be explicit about workflows** - numbered steps, clear sequences
4. **Include edge cases** - document error handling and special scenarios
5. **Reference external docs** - link to official documentation when appropriate
6. **Keep it maintainable** - simple structure, clear organization

## Anti-Patterns to Avoid

❌ Don't use second-person voice ("you should", "you can")
❌ Don't duplicate content between SKILL.md and references
❌ Don't create skills >5,000 words without using references
❌ Don't forget YAML frontmatter
❌ Don't use inconsistent naming conventions
❌ Don't skip examples - they're critical for agent understanding

## Related Documentation

- Agent Skills Specification: https://agentskills.io/
- GitLab Repository: https://gitlab.wikimedia.org/santhosh/wiki-skills
- Installation: `npx skills add https://gitlab.wikimedia.org/santhosh/wiki-skills`

---

**Note**: This is a documentation repository. There are no linters, formatters, or test runners. Quality is ensured through manual review and real-world testing with AI agents.