feat: instruction patches
This commit is contained in:
parent
dc4a6a12f5
commit
15052a1965
|
|
@ -1,47 +1,97 @@
|
||||||
# Assets Folder Standard
|
# 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
|
```yaml
|
||||||
assets_folder: assets/{slug}/
|
assets_folder: assets/{slug}/
|
||||||
```
|
```
|
||||||
|
|
||||||
## Структура папки
|
## Folder Structure
|
||||||
|
|
||||||
```
|
```
|
||||||
assets/{slug}/
|
assets/{slug}/
|
||||||
├── screenshots/ # скриншоты для статьи
|
├── outline.md # Article structure (@architect)
|
||||||
├── diagrams/ # диаграммы
|
├── text.md # Article body (@writer → @editor → @seo)
|
||||||
└── other/ # прочие файлы
|
├── 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` |
|
||||||
|
|
||||||
| Агент | Действие |
|
## Main Article File
|
||||||
|-------|----------|
|
|
||||||
| Human | Добавляет скриншоты перед передачей @writer |
|
|
||||||
| @writer | Вставляет ссылки на изображения из этой папки |
|
|
||||||
| @image-gen | Генерирует спеки для изображений, которые будут сохранены сюда |
|
|
||||||
|
|
||||||
## Формат ссылок в статье
|
Contains metadata and links only — NO duplicated content:
|
||||||
|
|
||||||
```markdown
|
```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