Marketing Practitioner

A research-first marketing decision system for AI agents.

Learn the market before writing the copy.

Version: v0.9.0 License: MIT Language: English Format: Agent Skill skills.sh

Marketing Practitioner helps an agent turn market evidence into bounded decisions across research, segmentation, positioning, commercial design, messaging, landing pages, email, social content, commerce, search/discovery, paid media, diagnosis, experiments, localization, and learning.

It is not a prompt pack or growth-hack library. The runtime starts from the current job, freezes decisions that are already resolved, loads deeper knowledge only when it can change the open decision, and returns the minimum useful output.

Quick start

npx skills add quocbao201104/marketing-practitioner

Then describe:

  1. what you are trying to do;
  2. what facts, evidence, or decisions you already have;
  3. where the result will be used, if that changes the answer.

You do not need to know terms such as ICP, JTBD, attribution, retrieval, or willingness to pay. The Task Specification Guide can compile rough notes into the smallest sufficient task specification without inventing missing facts.

Read TASK-SPECIFICATION-GUIDE.md.
Use what I already provided to compile the smallest sufficient task specification.
Preserve resolved decisions and do not invent missing facts or constraints.
Then execute the task with Marketing Practitioner.

Representative tasks

  • synthesize interviews, reviews, surveys, support records, and sales notes without turning recurrence into prevalence;
  • choose a segment, relevant alternative, positioning, value, proof, or trade-off;
  • decide packaging, pricing metric, commitment, eligibility, modifiers, or commercial transitions;
  • build or critique message hierarchy, claims, proof, copy, landing-page architecture, and email communication;
  • adapt resolved content to a platform without reopening strategy;
  • interpret commerce, search/discovery, social, email, or paid-media state without importing platform folklore;
  • diagnose a performance change before rewriting creative;
  • design or interpret an experiment and preserve reusable learning.

The detailed chapter and platform map lives in the handbook navigation. Social and commerce provider navigation is under platforms.

Reasoning model

The controller uses seven jobs:

WRITE · DECIDE · DIAGNOSE · RESEARCH / UNDERSTAND · ADAPT · TEST · LEARN

For each task it:

identify the current job
→ freeze resolved state
→ name the open decision
→ identify decision-changing evidence
→ select owners by dependency
→ load the smallest useful knowledge route
→ pass forward only material state
→ produce and validate the minimum sufficient output

Large knowledge surfaces are addressable through routing-index.json and get-knowledge.py. File paths and headings are implementation details; logical route IDs are the stable interface.

Evidence discipline

The skill is designed to preserve distinctions that commonly collapse in marketing work:

observation ≠ interpretation ≠ hypothesis ≠ decision
qualitative recurrence ≠ population prevalence
association / attribution ≠ causality / incrementality
eligible ≠ delivered ≠ attended to
interaction ≠ intent or preference
reported ≠ optimization-eligible
displayed commercial state ≠ universal authoritative state

It never has authority to invent product, finance, legal, operational, sales, platform, or customer facts. Current provider rules remain just-in-time dependencies rather than permanent universal laws.

Repository map

skills/marketing-practitioner/
  SKILL.md                  governing runtime controller
  agents/openai.yaml        optional UI metadata and explicit invocation starter
  routing-index.json        logical knowledge address table
  handbook/                 governed practitioner knowledge
  platforms/                scoped social and commerce modules
  references/               evidence ledgers and bibliography
  scripts/                  deterministic routing checks

research/                   theory lineage and rejected hypotheses
evals/                      adversarial cases, smokes, and behavioral harness
scripts/verify.ps1          sole local/CI verification entrypoint

Deep research stays outside the installable runtime unless it survives scope, evidence, and decision-value review.

Verification and behavioral evidence

Run the same gate used by CI:

.\scripts\verify.ps1

It validates the package with the repository validator and the installed Codex validator when discoverable, checks 58 routing mechanics and 249 routes/203 evidence sources, runs the Pressure Discovery and behavioral harness tests, and verifies UTF-8/generated-artifact hygiene.

The frozen 48-run behavioral pilot used 12 cases, two arms, two repetitions, gpt-5.6-terra, and medium reasoning. It produced eight both_pass pairs, three operationally invalid pairs, and one unresolved pair; it showed no baseline-only or skill-only pass. The review was condition-blind but not independently human-adjudicated, so it is repository decision evidence—not a benchmark or universal reliability claim. See the pilot report.

A controller challenger reduced initial controller words by 75% but increased activation-unverified runs from 3/24 to 7/24, so it was rejected and not promoted.

Status

Current release: v0.9.0 — Paid Media Architecture.

The installable skill passes current package validation and deterministic repository checks. Its knowledge includes bounded Commercial Design, Landing-Page, Email, Search & Discovery, Paid Media, social/content-environment, and commerce/product-discovery layers.

The project does not claim complete knowledge of private ranking, retrieval, or ad-delivery systems; universal platform, pricing, landing-page, email, or attribution rules; legal/provider compliance for every context; benchmark-grade quality; or universal runtime reliability. Improvement should follow concrete failures and evidence, not architecture growth for its own sake.

Installation and manual use

npx skills add quocbao201104/marketing-practitioner
git clone https://github.com/quocbao201104/marketing-practitioner.git

The governing instructions are skills/marketing-practitioner/SKILL.md.

Feedback and real-world reports

Real-world usage is especially valuable at this stage. If Marketing Practitioner makes a poor decision, overcomplicates a simple task, misses supplied evidence, reopens a resolved decision, chooses the wrong knowledge path, behaves inconsistently across repeats, or produces an unexpectedly useful result, please open a behavior report.

A useful report includes the task, relevant sanitized context, expected behavior, observed behavior, model/runtime, skill version, and whether the behavior is reproducible. Reports that expose a generalizable failure may be converted into anonymized behavioral evaluation cases or regression tests.

Please do not include confidential customer, company, credential, or personal data.

Contributing

See CONTRIBUTING.md. Contributions should preserve UTF-8, source fidelity, decision scope, resolved-state behavior, fast paths, owner boundaries, and the distinction between observation, attribution, and causality. New top-level reasoning capabilities require a demonstrated decision-relevant gap before implementation.

Attribution

The repository synthesizes marketing research, methodological literature, current provider documentation, information-retrieval and recommender research, pricing/commercial-design research, usability research, and practical writing methods. See THIRD_PARTY_NOTICES.md, the bibliography, and scoped evidence references.

License

MIT. See LICENSE.