# AT Protocol Expert Skill for Claude Code

Transform Claude into an AT Protocol development expert with comprehensive, up-to-date knowledge from the official atproto.com documentation.

## Quick Start

1. **Clone or download this repository**

2. **Install the skill** (choose one):

   For this project only:
   ```bash
   # Already in the right place if you cloned this repo!
   cd .claude/skills/atproto
   node fetch-docs.js
   ```

   For all your projects:
   ```bash
   cp -r .claude/skills/atproto ~/.claude/skills/
   cd ~/.claude/skills/atproto
   node fetch-docs.js
   ```

3. **Start using it** in Claude Code:
   ```
   "How do I create a post on Bluesky using the AT Protocol?"
   "Explain the difference between DIDs and handles"
   "Help me build a custom feed generator"
   ```

## What You Get

An expert AI assistant that knows:

- **AT Protocol fundamentals** - Architecture, federation, decentralization
- **Identity systems** - DIDs, handles, verification
- **Data management** - Repositories, records, schemas
- **Bluesky APIs** - All 292 Lexicon definitions for feeds, posts, social graph, chat, and more
- **Authentication** - OAuth flows, sessions, app passwords
- **Advanced topics** - Custom feeds, moderation tools, self-hosting PDS
- **Current specs** - All technical specifications and protocol details

## Knowledge Sources

This skill automatically fetches and organizes:

- ✅ **37 conceptual guides** from atproto.com
- ✅ **36 technical specifications** covering all protocol details
- ✅ **292 Lexicon schemas** (complete API definitions)
- ✅ **6 in-depth articles** on protocol design and philosophy
- ✅ **Official repository documentation**

**Total: 373 files** of authoritative AT Protocol knowledge

## Perfect For

- 🆕 First-time AT Protocol developers
- 📱 Bluesky app builders
- 🔄 Custom feed generator creators
- 🛡️ Moderation tool developers
- 🖥️ Self-hosting PDS operators
- 🔧 SDK users (TypeScript, Python, etc.)
- 🏗️ Protocol contributors

## Features

- 🔄 **Always current** - Simple update command fetches latest docs
- 📚 **Comprehensive** - Covers everything from basics to advanced topics
- 🎯 **Accurate** - Based on official sources only
- 🚀 **Ready to share** - Commit to your repo for team use
- 💡 **Context-aware** - Claude adapts to your expertise level

## Updating Documentation

Keep your knowledge base fresh (ATProto evolves quickly!):

```bash
cd .claude/skills/atproto
npm run update
# or: node fetch-docs.js
```

**Recommended frequency**: Weekly, or before starting a new ATProto project

## Example Questions to Ask

**Getting Started:**
- "What is the AT Protocol and how does it work?"
- "How do I set up a development environment for ATProto?"
- "What SDKs are available for AT Protocol development?"

**Building Features:**
- "How do I create a post with an image?"
- "Implement OAuth authentication for my app"
- "How do I query a user's timeline?"
- "Show me how to implement follow/unfollow"

**Advanced Topics:**
- "How do feed generators work in ATProto?"
- "Explain the repository sync protocol"
- "What's the structure of the Bluesky firehose?"
- "How do I build a custom moderation service?"

**API Reference:**
- "What fields are in app.bsky.feed.post?"
- "List all the methods in com.atproto.repo"
- "How does the OAuth PKCE flow work in ATProto?"

## Repository Structure

```
atproto-claude-skill/
├── README.md                    # This file
└── .claude/
    └── skills/
        └── atproto/
            ├── SKILL.md         # Skill definition (Claude reads this)
            ├── README.md        # Detailed skill documentation
            ├── package.json     # Convenience scripts
            ├── fetch-docs.js    # Documentation updater
            └── knowledge/       # 373 organized doc files (auto-generated)
                ├── INDEX.md
                ├── guides/
                ├── specs/
                ├── articles/
                ├── lexicons/
                └── readme/
```

## Requirements

- Claude Code
- Node.js (for fetching/updating documentation)
- Internet connection (for initial setup and updates)

## Sharing with Your Team

This skill is designed to be shared! Just:

1. Commit the entire `.claude/skills/atproto` directory to your repository
2. Include the `knowledge/` folder (so teammates don't need to re-fetch)
3. Team members can start using it immediately
4. Update periodically and commit changes to keep everyone current

## Official Sources

Documentation is fetched from:

- 🌐 **Website**: https://atproto.com
- 📦 **Website Repo**: https://github.com/bluesky-social/atproto-website (guides, specs, articles)
- ⚙️ **Protocol Repo**: https://github.com/bluesky-social/atproto (lexicon schemas)

All content is official and maintained by Bluesky Social.

## Contributing

To improve this skill:

1. Fork the repository
2. Enhance the fetch script, skill prompt, or documentation
3. Submit a pull request
4. Share with the community!

Ideas for contributions:
- Better documentation organization
- Additional context in SKILL.md
- Example code snippets
- Multi-language support
- Automated update scheduling

## Troubleshooting

**Skill not working?**
- Ensure `.claude/skills/atproto/SKILL.md` exists
- Run the fetch script to populate knowledge base
- Ask a specific ATProto question to trigger the skill

**Fetch script errors?**
- Check internet connection
- Verify Node.js is installed
- GitHub API rate limits: wait and retry

**Old information?**
- Run `npm run update` in the skill directory

## Version

**Current version**: 1.0.0
**Last updated**: 2025-10-16
**Knowledge base**: Fetches from latest official repositories

## License

This skill code is provided as-is for use with Claude Code.

The AT Protocol documentation and schemas are licensed by Bluesky Social. See their repositories for license details.

## Support & Links

- 📖 [AT Protocol Documentation](https://atproto.com)
- 💬 [Bluesky Developer Discord](https://discord.gg/bluesky)
- 🐛 [AT Protocol Issues](https://github.com/bluesky-social/atproto/issues)
- 🤖 [Claude Code Docs](https://docs.claude.com/claude-code)

---

**Ready to build on AT Protocol?** Install the skill and start asking questions!