feat: instruction patches
This commit is contained in:
parent
dc4a6a12f5
commit
15052a1965
|
|
@ -1,47 +1,97 @@
|
|||
# Assets Folder Standard
|
||||
|
||||
## Поле frontmatter: assets_folder
|
||||
## Overview
|
||||
|
||||
Для статей со скриншотами и другими визуальными материалами добавляем во frontmatter:
|
||||
Each article uses an assets folder for working files. The main article file serves as a "card" moving through the pipeline, while actual content lives in assets.
|
||||
|
||||
## Frontmatter
|
||||
|
||||
Add to the main article file:
|
||||
|
||||
```yaml
|
||||
assets_folder: assets/{slug}/
|
||||
```
|
||||
|
||||
## Структура папки
|
||||
## Folder Structure
|
||||
|
||||
```
|
||||
assets/{slug}/
|
||||
├── screenshots/ # скриншоты для статьи
|
||||
├── diagrams/ # диаграммы
|
||||
└── other/ # прочие файлы
|
||||
├── outline.md # Article structure (@architect)
|
||||
├── text.md # Article body (@writer → @editor → @seo)
|
||||
├── seo-metadata.md # SEO title, description, keywords (@seo)
|
||||
├── log-chat.md # Agent activity log (all agents)
|
||||
├── hero.png|.jpg # Cover image
|
||||
└── images/ # Screenshots, diagrams, illustrations
|
||||
```
|
||||
|
||||
Подпапки создаются по необходимости. Для простых статей можно класть файлы прямо в корень `assets/{slug}/`.
|
||||
## Agent Workflow
|
||||
|
||||
## Использование
|
||||
| Stage | Agent | Reads | Writes |
|
||||
|-------|-------|-------|--------|
|
||||
| Planning | @architect | main file | `outline.md` |
|
||||
| Drafting | @writer | `outline.md` | `text.md` |
|
||||
| Editing | @editor | `text.md`, `log-chat.md` | `text.md`, `log-chat.md` |
|
||||
| SEO | @seo | `text.md`, `log-chat.md` | `text.md`, `seo-metadata.md`, `log-chat.md` |
|
||||
| Images | @image-gen | `text.md` | image specs, `log-chat.md` |
|
||||
|
||||
| Агент | Действие |
|
||||
|-------|----------|
|
||||
| Human | Добавляет скриншоты перед передачей @writer |
|
||||
| @writer | Вставляет ссылки на изображения из этой папки |
|
||||
| @image-gen | Генерирует спеки для изображений, которые будут сохранены сюда |
|
||||
## Main Article File
|
||||
|
||||
## Формат ссылок в статье
|
||||
Contains metadata and links only — NO duplicated content:
|
||||
|
||||
```markdown
|
||||
|
||||
---
|
||||
title: "Article Title"
|
||||
author: henry-technical
|
||||
status: drafting
|
||||
assets_folder: assets/my-article/
|
||||
---
|
||||
|
||||
# Outline
|
||||
See [outline.md](assets/my-article/outline.md)
|
||||
|
||||
# Draft
|
||||
See [text.md](assets/my-article/text.md)
|
||||
|
||||
# SEO
|
||||
See [seo-metadata.md](assets/my-article/seo-metadata.md)
|
||||
|
||||
# Activity Log
|
||||
See [log-chat.md](assets/my-article/log-chat.md)
|
||||
```
|
||||
|
||||
## Когда использовать
|
||||
## SEO Metadata Format
|
||||
|
||||
Папка создаётся только когда статье нужны визуальные материалы:
|
||||
- Скриншоты интерфейса
|
||||
- Диаграммы и схемы
|
||||
- Иллюстрации
|
||||
```markdown
|
||||
# SEO Metadata
|
||||
|
||||
Для статей без изображений поле `assets_folder` не добавляется.
|
||||
## Title
|
||||
[60 chars max, primary keyword included]
|
||||
|
||||
## Meta Description
|
||||
[155 chars max, compelling, keyword included]
|
||||
|
||||
## Target Keywords
|
||||
- Primary: [main keyword]
|
||||
- Secondary: [2-3 related]
|
||||
|
||||
## URL Slug
|
||||
[short-descriptive-slug]
|
||||
```
|
||||
|
||||
## Image Naming
|
||||
|
||||
```
|
||||
images/
|
||||
├── diagram-{topic}.png
|
||||
├── screenshot-{description}.png
|
||||
├── illustration-{topic}.png
|
||||
└── comparison-{topic}.png
|
||||
```
|
||||
|
||||
## Log Chat
|
||||
|
||||
See [log-chat-format.md](log-chat-format.md) for detailed format.
|
||||
|
||||
---
|
||||
|
||||
*Стандарт введён: 2026-01-06*
|
||||
*Updated: 2025-01-07*
|
||||
|
|
|
|||
|
|
@ -0,0 +1,97 @@
|
|||
# Inline Edits Syntax
|
||||
|
||||
## Purpose
|
||||
|
||||
Human can add quick drafts and notes directly in article text using square brackets. Agents process these and integrate them into the final article.
|
||||
|
||||
## Syntax: `[text]`
|
||||
|
||||
Square brackets contain human-written content that needs processing:
|
||||
|
||||
```markdown
|
||||
[claude use editing tool to add this. TODO: insert the correct tool name]
|
||||
```
|
||||
|
||||
**Becomes:**
|
||||
```markdown
|
||||
Claude uses `str_replace` to append content.
|
||||
```
|
||||
|
||||
The agent:
|
||||
- Rewrites the text in article's tone and style
|
||||
- Translates to English if needed
|
||||
- Completes any TODO instructions inside
|
||||
- Applies proper formatting
|
||||
- Removes the brackets
|
||||
|
||||
## Examples
|
||||
|
||||
**Input:**
|
||||
```markdown
|
||||
[тут надо объяснить что файл создается в home директории. TODO: уточни точный путь]
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```markdown
|
||||
The file is created in Claude's home directory at `/home/claude/`.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Input:**
|
||||
```markdown
|
||||
[this is important for understanding. the sandbox resets after timeout. TODO: check if 5 minutes is correct timeout]
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```markdown
|
||||
This is important to understand: the sandbox environment resets after approximately 5 minutes of inactivity.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Input:**
|
||||
```markdown
|
||||
The key directories are:
|
||||
[TODO: add table with paths and their descriptions]
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```markdown
|
||||
The key directories are:
|
||||
|
||||
| Path | Description |
|
||||
|------|-------------|
|
||||
| /home/claude/ | Working directory, volatile |
|
||||
| /mnt/user-data/outputs/ | Persistent, visible in sidebar |
|
||||
| /mnt/user-data/uploads/ | Your uploaded files |
|
||||
```
|
||||
|
||||
## Command: /apply
|
||||
|
||||
For @writer:
|
||||
|
||||
```
|
||||
/apply
|
||||
```
|
||||
|
||||
**Action:**
|
||||
1. Re-read entire `text.md`
|
||||
2. Find all `[bracketed content]`
|
||||
3. Process each: rewrite, translate, complete TODOs, format
|
||||
4. Remove brackets
|
||||
5. Log changes in `log-chat.md`
|
||||
|
||||
## Agent Responsibilities
|
||||
|
||||
| Agent | Role |
|
||||
|-------|------|
|
||||
| @writer | Process all bracketed content with `/apply` |
|
||||
| @editor | **Verify no unprocessed brackets remain** — final text must be clean |
|
||||
| Others | May process if within scope, or flag for @writer |
|
||||
|
||||
**Critical for @editor:** Before approving for publication, confirm the text contains zero `[brackets]`. Any remaining brackets = not ready for publish.
|
||||
|
||||
---
|
||||
|
||||
*Updated: 2025-01-07*
|
||||
|
|
@ -0,0 +1,103 @@
|
|||
# Log Chat Format
|
||||
|
||||
## Purpose
|
||||
|
||||
`log-chat.md` tracks agent activity across iterations. Critical for:
|
||||
- @editor seeing @seo changes (understanding SEO edits vs errors)
|
||||
- @writer seeing @editor feedback (knowing what to fix)
|
||||
- @seo seeing previous optimization attempts
|
||||
- Any agent understanding context of prior work
|
||||
|
||||
## When to Use
|
||||
|
||||
**Before work:** Read `log-chat.md` to understand previous iterations.
|
||||
|
||||
**After work:** Append your entry with what was done.
|
||||
|
||||
## Entry Format
|
||||
|
||||
```markdown
|
||||
## [YYYY-MM-DD] @agent-name
|
||||
|
||||
**Action:** Brief description of what was done
|
||||
|
||||
**Changes:**
|
||||
- file.md: what changed
|
||||
- another-file.md: what changed
|
||||
|
||||
**Notes:** Important decisions, reasoning, observations
|
||||
|
||||
**For next agent:** Specific instructions or warnings
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### @editor entry
|
||||
```markdown
|
||||
## 2025-01-07 @editor
|
||||
|
||||
**Action:** Review and feedback on draft
|
||||
|
||||
**Changes:**
|
||||
- text.md: no changes yet, feedback only
|
||||
|
||||
**Notes:**
|
||||
- Introduction too long, suggest cutting first paragraph
|
||||
- Code example in section 3 needs output screenshot
|
||||
- Tone inconsistent in conclusion
|
||||
|
||||
**For next agent:** @writer please address feedback above
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
### @seo entry
|
||||
```markdown
|
||||
## 2025-01-07 @seo
|
||||
|
||||
**Action:** SEO optimization pass
|
||||
|
||||
**Changes:**
|
||||
- text.md: added keywords to H2 headings, optimized first 100 words
|
||||
- seo-metadata.md: created with title, description, keywords
|
||||
|
||||
**Notes:**
|
||||
- Primary keyword "claude sandbox" added 3 times naturally
|
||||
- Rewrote opening paragraph for SERP snippet optimization
|
||||
- All images now have keyword-rich alt text
|
||||
|
||||
**For next agent:** Text changes are SEO-driven, not style errors
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
### @writer entry (after iteration)
|
||||
```markdown
|
||||
## 2025-01-08 @writer
|
||||
|
||||
**Action:** Applied editor feedback
|
||||
|
||||
**Changes:**
|
||||
- text.md: shortened intro, fixed tone in conclusion
|
||||
|
||||
**Notes:**
|
||||
- Kept SEO optimizations from @seo
|
||||
- Added transition paragraph between sections 2-3
|
||||
|
||||
**For next agent:** Ready for final review
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Key Principles
|
||||
|
||||
1. **Be specific** — "fixed intro" is useless, "removed first paragraph, added hook question" is helpful
|
||||
2. **Explain reasoning** — especially for @seo changes that might look like errors
|
||||
3. **Direct next agent** — say who should act and what they should focus on
|
||||
4. **Keep it brief** — this is a log, not documentation
|
||||
|
||||
---
|
||||
|
||||
*Updated: 2025-01-07*
|
||||
|
|
@ -0,0 +1,55 @@
|
|||
# Patch: @image-gen Agent
|
||||
|
||||
**Date:** 2025-01-07
|
||||
**Applies to:** desktop-agents/006-image-gen/
|
||||
|
||||
---
|
||||
|
||||
## Creative Visual Analysis
|
||||
|
||||
You're good at what you do. This is a guide, not rigid rules.
|
||||
|
||||
**Core idea:** Read the article text and think about where images would improve reader experience. Look for places where a visual would explain better than words, break up dense content, or make the article more engaging.
|
||||
|
||||
### Things to Notice
|
||||
|
||||
When reading through the article, keep an eye out for:
|
||||
|
||||
- **Tables** that might work better as diagrams (especially flows, processes, comparisons)
|
||||
- **Long stretches of text** without any visual break — readers get tired
|
||||
- **Complex concepts** that would click faster with a diagram
|
||||
- **Code blocks** that could use a screenshot showing what happens when you run them
|
||||
- **Comparisons** ("A vs B", "before/after") that beg for a side-by-side visual
|
||||
- **Numbers and statistics** that could become an infographic
|
||||
|
||||
Also check: Does the article have a hero image? If not, probably needs one.
|
||||
|
||||
---
|
||||
|
||||
## How to Work
|
||||
|
||||
1. Read through `assets/{slug}/text.md`
|
||||
2. Note places where visuals would help
|
||||
3. **Discuss with the user** — share your suggestions, get feedback
|
||||
4. Refine based on conversation
|
||||
5. Create specs for agreed images
|
||||
6. Log recommendations in `log-chat.md`
|
||||
|
||||
Don't work autonomously — this is collaborative. Propose ideas, explain why, let the human decide what actually gets made.
|
||||
|
||||
---
|
||||
|
||||
## Workflow
|
||||
|
||||
```
|
||||
assets/{slug}/text.md ← read, think about visual opportunities
|
||||
assets/{slug}/images/ ← existing images
|
||||
assets/{slug}/hero.png ← hero image
|
||||
assets/{slug}/log-chat.md ← log your recommendations
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Read Also
|
||||
|
||||
- [log-chat-format.md](log-chat-format.md) — how to log your work
|
||||
|
|
@ -0,0 +1,85 @@
|
|||
# Patch: @seo Agent
|
||||
|
||||
**Date:** 2025-01-07
|
||||
**Applies to:** desktop-agents/005-seo/
|
||||
|
||||
---
|
||||
|
||||
## Additional Responsibility: Text Optimization
|
||||
|
||||
You don't just create SEO metadata. You **actively optimize the article text**.
|
||||
|
||||
### Title Analysis
|
||||
|
||||
- Check headline strength (power words, numbers, emotion)
|
||||
- Compare with competitors in SERP
|
||||
- Differentiate if too similar to competitors
|
||||
- Suggest stronger alternatives if weak
|
||||
|
||||
### Heading Optimization
|
||||
|
||||
- Verify hierarchy (H1 → H2 → H3, no skips)
|
||||
- Insert keywords into headings where natural
|
||||
- Ensure headings are descriptive, not generic
|
||||
|
||||
### Image Alt Text
|
||||
|
||||
- Check all images have alt text
|
||||
- Add keywords to alt where appropriate
|
||||
- Keep alt descriptive for accessibility
|
||||
|
||||
### Body Text
|
||||
|
||||
- Light edits to insert keywords naturally
|
||||
- Optimize first 100 words (SERP snippet priority)
|
||||
- Improve readability without changing meaning
|
||||
- **Be careful** — preserve author's voice and style
|
||||
|
||||
---
|
||||
|
||||
## Checklist
|
||||
|
||||
Before finishing, verify:
|
||||
|
||||
**Metadata**
|
||||
- [ ] SEO title with primary keyword (60 chars)
|
||||
- [ ] Meta description compelling + keyword (155 chars)
|
||||
- [ ] URL slug short and descriptive
|
||||
|
||||
**Title**
|
||||
- [ ] Compared with SERP competitors
|
||||
- [ ] Has differentiation/uniqueness
|
||||
- [ ] Power words if appropriate
|
||||
|
||||
**Headings**
|
||||
- [ ] Correct hierarchy
|
||||
- [ ] Keywords in headings where natural
|
||||
- [ ] Descriptive, not generic
|
||||
|
||||
**Images**
|
||||
- [ ] All have alt text
|
||||
- [ ] Keywords in alt where appropriate
|
||||
|
||||
**Text**
|
||||
- [ ] First 100 words optimized
|
||||
- [ ] Keywords appear naturally
|
||||
- [ ] Readability preserved
|
||||
|
||||
---
|
||||
|
||||
## Workflow Update
|
||||
|
||||
```
|
||||
assets/{slug}/text.md ← read AND optimize
|
||||
assets/{slug}/seo-metadata.md ← create
|
||||
assets/{slug}/log-chat.md ← log your work and changes to text.md (important for @editor/@writer)
|
||||
```
|
||||
|
||||
**Critical:** Log all text changes in `log-chat.md` so other agents understand these are SEO optimizations, not errors.
|
||||
|
||||
---
|
||||
|
||||
## Read Also
|
||||
|
||||
- [inline-edits-syntax.md](inline-edits-syntax.md) — process `[TODO: @seo ...]`
|
||||
- [log-chat-format.md](log-chat-format.md) — how to log your changes
|
||||
Loading…
Reference in New Issue