Skip to content

NetFabric/intelligentium / .agents/skills/agent-markdown-best-practices

agent-markdown-best-practices

Verified

ALWAYS use when writing or reviewing agent-facing Markdown, including project instructions, skills and references, and custom-agent definitions. Covers only their shared content style: compact executable instructions, scannable information, active language, factual precision, and token efficiency. DO NOT USE FOR: artifact-specific structure, routing descriptions, metadata schemas, or prompt-body requirements; general Markdown documents; Markdown syntax or rendering rules.

Agent Markdown Best Practices

Agent-facing Markdown is operational context. Keep explanation when it changes interpretation or behavior; remove words that do not.

Core Rules

RuleDoDon't
Executable over descriptive"Run pnpm test""Make sure tests pass"
Concrete over aspirationalRecord verified commands and enforced conventionsDescribe practices the project does not follow
Active and imperative"Inspect the diff""The diff should be inspected"
No preambleStart with the role, rule, or first useful section"This file describes..."
No restatementLet headings, structured fields, and code express what they already sayRepeat metadata or section titles in prose
Structured over discursiveUse a table, short list, or numbered protocol for scannable factsHide operational facts in long paragraphs
Avoid duplicate sourcesKeep required instructions local; link supporting detail that remains available at use timeCopy nonessential background or policy prose into agent context
One purpose per sectionSplit unrelated concerns under clear headingsMix independent rules in one block

Compactness never removes a command, flag, constraint, caveat, or prerequisite that changes behavior. Cut words, not facts.

Workflow

  1. Verify claims against the repository, tool, or documented behavior; remove generic placeholders and aspirational rules.
  2. Apply the precision and compression rules to prose, instructions, and examples.
  3. Remove repeated conclusions, obvious callouts, and history that does not affect execution.

Reference Files

FileLoad When
references/compact-agent-content.mdStructuring or tightening any agent-facing Markdown
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 319kUpdated Claude CodeCodexVerifiedInstall