m3tam3re/AGENTS
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: update readme

Browse Source
This commit is contained in:
m3tm3re
2026-02-18 17:32:13 +01:00
parent 1f1eabd1ed
commit 1bc81fb38c
1 changed files with 89 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

157
README.md
View File

@@ -11,33 +11,42 @@ This repository serves as a **personal AI operating system** - a collection of s
- **Communications** - Email management, meeting scheduling, follow-up tracking
- **AI Development** - Tools for creating new skills and agent configurations
- **Memory & Context** - Persistent memory systems, conversation analysis
- **Document Processing** - PDF manipulation, spreadsheet handling, diagram generation
- **Custom Workflows** - Domain-specific automation and specialized agents
## 📂 Repository Structure
```
.
├── agent/ # Agent definitions (agents.json)
├── prompts/ # Agent system prompts (chiron.txt, chiron-forge.txt)
├── agents/ # Agent definitions (agents.json)
├── prompts/ # Agent system prompts (chiron.txt, chiron-forge.txt, etc.)
├── context/ # User profiles and preferences
│ └── profile.md # Work style, PARA areas, preferences
├── command/ # Custom command definitions
├── commands/ # Custom command definitions
│ └── reflection.md
├── skill/ # Opencode Agent Skills (11+ skills)
│ ├── task-management/ # PARA-based productivity
│ ├── skill-creator/ # Meta-skill for creating skills
│ ├── reflection/ # Conversation analysis
│ ├── communications/ # Email & messaging
│ ├── calendar-scheduling/ # Time management
│ ├── mem0-memory/ # Persistent memory
│ ├── research/ # Investigation workflows
│ ├── knowledge-management/ # Note capture & organization
├── skills/ # Opencode Agent Skills (18 skills)
│ ├── agent-development/ # Agent creation and configuration
│ ├── basecamp/ # Basecamp project management
│ ├── brainstorming/ # Ideation & strategic thinking
│ └── plan-writing/ # Project planning templates
│ ├── doc-translator/ # Documentation translation
│ ├── excalidraw/ # Architecture diagrams
│ ├── frontend-design/ # UI/UX design patterns
│ ├── memory/ # Persistent memory system
│ ├── mem0-memory/ # DEPRECATED (use memory)
│ ├── msteams/ # Microsoft Teams integration
│ ├── obsidian/ # Obsidian vault management
│ ├── outline/ # Outline wiki integration
│ ├── outlook/ # Outlook email & calendar
│ ├── pdf/ # PDF manipulation toolkit
│ ├── prompt-engineering-patterns/ # Prompt patterns
│ ├── reflection/ # Conversation analysis
│ ├── skill-creator/ # Meta-skill for creating skills
│ ├── systematic-debugging/ # Debugging methodology
│ └── xlsx/ # Spreadsheet handling
├── scripts/ # Repository utility scripts
│ └── test-skill.sh # Test skills without deploying
├── .beads/ # Issue tracking database
├── rules/ # Development rules and conventions
├── tools/ # Utility tools
├── AGENTS.md # Developer documentation
└── README.md # This file
```
@@ -65,15 +74,15 @@ inputs.agents = {
# In your home-manager module (e.g., opencode.nix)
xdg.configFile = {
"opencode/skill".source = "${inputs.agents}/skill";
"opencode/skills".source = "${inputs.agents}/skills";
"opencode/context".source = "${inputs.agents}/context";
"opencode/command".source = "${inputs.agents}/command";
"opencode/commands".source = "${inputs.agents}/commands";
"opencode/prompts".source = "${inputs.agents}/prompts";
};
# Agent config is embedded into config.json, not deployed as files
programs.opencode.settings.agent = builtins.fromJSON
(builtins.readFile "${inputs.agents}/agent/agents.json");
(builtins.readFile "${inputs.agents}/agents/agents.json");
```
Rebuild your system:
@@ -82,7 +91,7 @@ Rebuild your system:
home-manager switch
```
**Note**: The `agent/` directory is NOT deployed as files. Instead, `agents.json` is read at Nix evaluation time and embedded into the opencode `config.json`.
**Note**: The `agents/` directory is NOT deployed as files. Instead, `agents.json` is read at Nix evaluation time and embedded into the opencode `config.json`.
#### Option 2: Manual Installation
@@ -92,8 +101,11 @@ Clone and symlink:
# Clone repository
git clone https://github.com/yourusername/AGENTS.git ~/AGENTS
# Create symlink to Opencode config directory
ln -s ~/AGENTS ~/.config/opencode
# Create symlinks to Opencode config directory
ln -s ~/AGENTS/skills ~/.config/opencode/skills
ln -s ~/AGENTS/context ~/.config/opencode/context
ln -s ~/AGENTS/commands ~/.config/opencode/commands
ln -s ~/AGENTS/prompts ~/.config/opencode/prompts
```
### Verify Installation
@@ -101,8 +113,8 @@ ln -s ~/AGENTS ~/.config/opencode
Check that Opencode can see your skills:
```bash
# Skills should be available at ~/.config/opencode/skill/
ls ~/.config/opencode/skill/
# Skills should be available at ~/.config/opencode/skills/
ls ~/.config/opencode/skills/
```
## 🎨 Creating Your First Skill
@@ -112,19 +124,19 @@ Skills are modular packages that extend Opencode with specialized knowledge and
### 1. Initialize a New Skill
```bash
python3 skill/skill-creator/scripts/init_skill.py my-skill-name --path skill/
python3 skills/skill-creator/scripts/init_skill.py my-skill-name --path skills/
```
This creates:
- `skill/my-skill-name/SKILL.md` - Main skill documentation
- `skill/my-skill-name/scripts/` - Executable code (optional)
- `skill/my-skill-name/references/` - Reference documentation (optional)
- `skill/my-skill-name/assets/` - Templates and files (optional)
- `skills/my-skill-name/SKILL.md` - Main skill documentation
- `skills/my-skill-name/scripts/` - Executable code (optional)
- `skills/my-skill-name/references/` - Reference documentation (optional)
- `skills/my-skill-name/assets/` - Templates and files (optional)
### 2. Edit the Skill
Open `skill/my-skill-name/SKILL.md` and customize:
Open `skills/my-skill-name/SKILL.md` and customize:
```yaml
---
@@ -142,7 +154,7 @@ compatibility: opencode
### 3. Validate the Skill
```bash
python3 skill/skill-creator/scripts/quick_validate.py skill/my-skill-name
python3 skills/skill-creator/scripts/quick_validate.py skills/my-skill-name
```
### 4. Test the Skill
@@ -160,39 +172,46 @@ The test script creates a temporary config directory with symlinks to this repo'
## 📚 Available Skills
| Skill | Purpose | Status |
| ------------------------ | ------------------------------------------------------- | --------- |
| **task-management** | PARA-based productivity with Obsidian Tasks integration | ✅ Active |
| **skill-creator** | Guide for creating new Opencode skills | ✅ Active |
| **reflection** | Conversation analysis and skill improvement | ✅ Active |
| **communications** | Email drafts, follow-ups, message management | ✅ Active |
| **calendar-scheduling** | Time blocking, meeting management | ✅ Active |
| **mem0-memory** | Persistent memory storage and retrieval | ✅ Active |
| **research** | Investigation workflows, source management | ✅ Active |
| **knowledge-management** | Note capture, knowledge organization | ✅ Active |
| **basecamp** | Basecamp project & todo management via MCP | ✅ Active |
| **brainstorming** | General-purpose ideation with Obsidian save | ✅ Active |
| **plan-writing** | Project plans with templates (kickoff, tasks, risks) | ✅ Active |
| Skill | Purpose | Status |
| --------------------------- | -------------------------------------------------------------- | ------------ |
| **agent-development** | Create and configure Opencode agents | ✅ Active |
| **basecamp** | Basecamp project & todo management via MCP | ✅ Active |
| **brainstorming** | General-purpose ideation and strategic thinking | ✅ Active |
| **doc-translator** | Documentation translation to German/Czech with Outline publish | ✅ Active |
| **excalidraw** | Architecture diagrams from codebase analysis | ✅ Active |
| **frontend-design** | Production-grade UI/UX with high design quality | ✅ Active |
| **memory** | SQLite-based persistent memory with hybrid search | ✅ Active |
| **mem0-memory** | Legacy memory system (deprecated) | ⚠️ Deprecated |
| **msteams** | Microsoft Teams integration via Graph API | ✅ Active |
| **obsidian** | Obsidian vault management via Local REST API | ✅ Active |
| **outline** | Outline wiki integration for team documentation | ✅ Active |
| **outlook** | Outlook email, calendar, and contact management | ✅ Active |
| **pdf** | PDF manipulation, extraction, creation, and forms | ✅ Active |
| **prompt-engineering-patterns** | Advanced prompt engineering techniques | ✅ Active |
| **reflection** | Conversation analysis and skill improvement | ✅ Active |
| **skill-creator** | Guide for creating new Opencode skills | ✅ Active |
| **systematic-debugging** | Debugging methodology for bugs and test failures | ✅ Active |
| **xlsx** | Spreadsheet creation, editing, and analysis | ✅ Active |
## 🤖 AI Agents
### Chiron - Personal Assistant
### Primary Agents
**Configuration**: `agent/agents.json` + `prompts/chiron.txt`
| Agent | Mode | Purpose |
| ------------------- | ------- | ---------------------------------------------------- |
| **Chiron** | Plan | Read-only analysis, planning, and guidance |
| **Chiron Forge** | Build | Full execution and task completion with safety |
Chiron is a personal AI assistant focused on productivity and task management. Named after the wise centaur from Greek mythology, Chiron provides:
### Subagents (Specialists)
- Task and project management guidance
- Daily and weekly review workflows
- Skill routing based on user intent
- Integration with productivity tools (Obsidian, ntfy, n8n)
| Agent | Domain | Purpose |
| ------------------- | ---------------- | ------------------------------------------ |
| **Hermes** | Communication | Basecamp, Outlook, MS Teams |
| **Athena** | Research | Outline wiki, documentation, knowledge |
| **Apollo** | Private Knowledge| Obsidian vault, personal notes |
| **Calliope** | Writing | Documentation, reports, prose |
**Modes**:
- **Chiron** (Plan Mode) - Read-only analysis and planning (`prompts/chiron.txt`)
- **Chiron-Forge** (Worker Mode) - Full write access with safety prompts (`prompts/chiron-forge.txt`)
**Triggers**: Personal productivity requests, task management, reviews, planning
**Configuration**: `agents/agents.json` + `prompts/*.txt`
## 🛠️ Development Workflow
@@ -200,7 +219,7 @@ Chiron is a personal AI assistant focused on productivity and task management. N
Before committing:
1. **Validate skills**: `./scripts/test-skill.sh --validate` or `python3 skill/skill-creator/scripts/quick_validate.py skill/<name>`
1. **Validate skills**: `./scripts/test-skill.sh --validate` or `python3 skills/skill-creator/scripts/quick_validate.py skills/<name>`
2. **Test locally**: `./scripts/test-skill.sh --run` to launch opencode with dev skills
3. **Check formatting**: Ensure YAML frontmatter is valid
4. **Update docs**: Keep README and AGENTS.md in sync
@@ -210,9 +229,9 @@ Before committing:
### Essential Documentation
- **AGENTS.md** - Complete developer guide for AI agents
- **skill/skill-creator/SKILL.md** - Comprehensive skill creation guide
- **skill/skill-creator/references/workflows.md** - Workflow pattern library
- **skill/skill-creator/references/output-patterns.md** - Output formatting patterns
- **skills/skill-creator/SKILL.md** - Comprehensive skill creation guide
- **skills/skill-creator/references/workflows.md** - Workflow pattern library
- **skills/skill-creator/references/output-patterns.md** - Output formatting patterns
### Skill Design Principles
@@ -223,22 +242,25 @@ Before committing:
### Example Skills to Study
- **task-management/** - Full implementation with Obsidian Tasks integration
- **skill-creator/** - Meta-skill with bundled resources
- **reflection/** - Conversation analysis with rating system
- **basecamp/** - MCP server integration with multiple tool categories
- **brainstorming/** - Framework-based ideation with Obsidian markdown save
- **plan-writing/** - Template-driven document generation
- **memory/** - SQLite-based hybrid search implementation
## 🔧 Customization
### Modify Agent Behavior
Edit `agent/agents.json` for agent definitions and `prompts/*.txt` for system prompts:
Edit `agents/agents.json` for agent definitions and `prompts/*.txt` for system prompts:
- `agent/agents.json` - Agent names, models, permissions
- `agents/agents.json` - Agent names, models, permissions
- `prompts/chiron.txt` - Chiron (Plan Mode) system prompt
- `prompts/chiron-forge.txt` - Chiron-Forge (Worker Mode) system prompt
- `prompts/chiron-forge.txt` - Chiron Forge (Build Mode) system prompt
- `prompts/hermes.txt` - Hermes (Communication) system prompt
- `prompts/athena.txt` - Athena (Research) system prompt
- `prompts/apollo.txt` - Apollo (Private Knowledge) system prompt
- `prompts/calliope.txt` - Calliope (Writing) system prompt
**Note**: Agent changes require `home-manager switch` to take effect (config is embedded, not symlinked).
@@ -253,7 +275,7 @@ Edit `context/profile.md` to configure:
### Add Custom Commands
Create new command definitions in `command/` directory following the pattern in `command/reflection.md`.
Create new command definitions in `commands/` directory following the pattern in `commands/reflection.md`.
## 🌟 Use Cases
@@ -309,15 +331,14 @@ This repository contains personal configurations and skills. Feel free to use th
## 🔗 Links
- [Opencode](https://opencode.dev) - AI coding assistant
- [Beads](https://github.com/steveyegge/beads) - AI-native issue tracking
- [PARA Method](https://fortelabs.com/blog/para/) - Productivity methodology
- [Obsidian](https://obsidian.md) - Knowledge management platform
## 🙋 Questions?
- Check `AGENTS.md` for detailed developer documentation
- Review existing skills in `skill/` for examples
- See `skill/skill-creator/SKILL.md` for skill creation guide
- Review existing skills in `skills/` for examples
- See `skills/skill-creator/SKILL.md` for skill creation guide
---