bloggingskills: Instructions file for Claude Code

AGENTS.md

Guidance for agents and contributors working in this repo. It governs how skills are written so they stay consistent, portable, and on-brand. The brand is simple: content that doesn't read like AI.

What this repo is

A collection of Agent Skills for blogging. Each skill is a folder under skills/ with a SKILL.md and optional references/. Skills are model-invoked: the agent matches the user's request against each skill's description and loads the best fit. They also work as slash commands (/article, /humanize).

Skill structure

skills/<name>/
├── SKILL.md          # required, under 500 lines
└── references/       # optional, loaded on demand

• Frontmatter has exactly name and description, plus a metadata block with version.
  • name: lowercase, hyphenated, matches the folder name (1 to 64 chars).
  • description: the trigger, and the most important field. It does three jobs: (1) what the skill does, (2) the phrases a user would say to invoke it ("Also use when the user says '...'"), and (3) scope boundaries pointing to sibling skills ("For X, see Y."). The agent routes on this.
• Body: an H1 title, a second-person role line, an "Initial assessment" that reads shared context first, a numbered method, an "Output" section, and a "Related skills" line.
• Keep SKILL.md under 500 lines. Move depth into references/ and link to it.

The foundation contract

Two skills are read first by every writing skill:

• blog-context writes .agents/blog-context.md (niche, audience, voice). Every skill's "Initial assessment" reads it, so the user explains their blog once.
• house-style owns references/ai-tells.md, the writing rulebook. Every skill that produces prose loads it before drafting.

The rulebook is duplicated on purpose

references/ai-tells.md is the crown jewel. The canonical copy lives in house-style/. humanize/ and article/ each bundle a copy so they work when installed alone. If you edit the canonical file, re-sync the copies (cp skills/house-style/references/ai-tells.md skills/humanize/references/ai-tells.md, and the same for article/). scripts/validate.py fails if they drift.