How nowork-studio/toprank works
1. What this repo is
Toprank is not a traditional application or service; it is a collection of agent skills for Claude Code and Codex. Each skill is an instruction pack plus optional scripts and references that guide an AI agent to perform SEO or Google Ads tasks end-to-end.
2. Primary architectural boundary: skill-based workflows
The core unit is a SKILL.md file. The agent loads the skill, follows its workflow, and may call local scripts or external APIs. This means the “application logic” lives mostly in prompted procedures, not in a long-running server.
3. Two main product domains
The repo is split into:
- seo/ for SEO analysis, content, keyword research, metadata, schema, and CMS setup
- google-ads/ for Ads audit, account management, and ad copy generation
These are separate operational domains with different external systems, but they share the same skill packaging model.
4. SEO analysis subsystem
seo/seo-analysis/ is the most code-heavy skill. It combines:
- Search Console analysis scripts
- CMS detection and content fetch/push scripts
- preflight checks for multiple CMSs
- URL inspection and site audit helpers
This skill is the main data-ingestion and diagnostic pipeline for SEO.
5. CMS integration boundary
The SEO analysis skill includes adapters for several CMS platforms:
- Contentful
- Ghost
- Strapi
- WordPress
The repo treats CMSs as pluggable backends. The analysis workflow can detect the CMS, fetch content, and in some cases push SEO updates back to the CMS.
6. Google Search Console data flow
The SEO audit flow centers on Search Console:
- setup guidance and site listing
- pulling 90 days of query/page data
- analyzing traffic drops, CTR issues, and position opportunities
- generating prioritized actions
The scripts in seo/seo-analysis/scripts/ are the main bridge between the agent and GSC.
7. SEO content creation pipeline
seo/content-writer/ consumes findings from analysis and turns them into publishable content. It is supported by reference docs for writing quality and SEO conventions, but it does not appear to have heavy runtime code; it is primarily a guided content-generation skill.
8. Keyword, metadata, and schema support skills
These are narrower SEO specialist skills:
- keyword-research/ discovers, classifies, and prioritizes terms
- meta-tags-optimizer/ generates title tags, descriptions, and social tags
- schema-markup-generator/ produces JSON-LD structured data
They form a content optimization toolchain that can feed the content writer or standalone optimization tasks.
9. Google Ads subsystem
google-ads/ads-audit/, google-ads/ads/, and google-ads/ads-copy/ cover the Ads side:
- auditing account health and spend efficiency
- managing campaigns, keywords, bids, negatives, and ads
- generating RSA ad copy and A/B tests
The audit skill also creates reusable business context for the rest of the Ads workflows.
10. External Ads service integration
The Ads workflows depend on an external MCP-based AdsAgent integration. The repo includes google-ads/ads/mcporter.json, which is the service configuration boundary for connecting the agent to Google Ads actions and reads.
11. Persistent state and cross-skill reuse
One notable stateful element is the business context saved by ads audit to ~/.adsagent/business-context.json. That file is reused by later ads-copy or optimization tasks, so the Ads side has a shared local memory layer across skills.
12. Installer and runtime integration
The setup flow and bin/ utilities are the repo’s operational glue. bin/toprank-config and bin/toprank-update-check support installation/configuration and version management, while the setup process registers skills into the correct agent host directories (.agents/skills for Codex, ~/.claude/skills for Claude Code).
13. Testing and validation architecture
The repo includes layered tests:
- unit tests for scripts and URL inspection
- end-to-end skill routing and execution tests
- LLM evaluation tests
- fixtures that mock gcloud and Search Console responses
This shows the project validates both deterministic script behavior and agent-driven skill behavior.
14. Documentation and reference-driven design
The references/ folders under each skill are part of the runtime design, not just docs. They provide frameworks, templates, and validation rules that shape the agent’s output quality. In architecture terms, they are the “knowledge base” each skill depends on.
15. Overall data flow
Typical flow is: user trigger → skill selection → SKILL.md workflow → local scripts/reference docs → external service calls to Google Search Console or Google Ads / CMS APIs → structured report or direct changes. The repo is therefore a tooling-and-workflow platform for AI agents, with external integrations and local state, rather than a conventional monolithic app.
Main entry points: seo-analysis/SKILL.md SEO Analysis · ads-audit/SKILL.md Ads Audit · setup Setup · content-writer/SKILL.md Content Writer
Components 25
Platform
Installation, upgrade, and skill packaging for agent hosts.
- Agent Hosts · Codex and Claude Code skill directories used during installation.
- Setup · Registers skills and prepares local agent runtime integration.
setup - Config Tool · Operational glue for configuration and setup tasks.
bin/toprank-config - Update Check · Checks for version updates and maintenance state.
bin/toprank-update-check - Upgrade Skill · Skill used to guide repository upgrade and maintenance workflows.
toprank-upgrade/SKILL.md
SEO
SEO analysis and content optimization skills.
- SEO Analysis · Main SEO workflow that coordinates GSC analysis, CMS inspection, and update helpers.
seo/seo-analysis/SKILL.md - GSC Analyze · Pulls and analyzes Search Console query/page data for drops, CTR, and opportunities.
seo/seo-analysis/scripts/analyze_gsc.py - CMS Detect · Detects the site CMS before content fetch or update steps.
seo/seo-analysis/scripts/cms_detect.py - CMS Adapters · Pluggable content backends for Contentful, Ghost, Strapi, and WordPress.
- Preflight · CMS-specific readiness checks before content or SEO operations.
seo/seo-analysis/scripts/preflight.py - URL Inspection · Inspects URLs as part of SEO diagnostics and audit flows.
seo/seo-analysis/scripts/url_inspection.py - GSC Setup · Setup guidance and operating notes for Search Console access.
seo/seo-analysis/references/gsc_setup.md - Content Writer · Turns SEO findings into publishable content plans and drafts.
seo/content-writer/SKILL.md - Keyword Research · Discovers, classifies, and prioritizes target terms.
seo/keyword-research/SKILL.md - Meta Optimizer · Generates title tags, descriptions, and social metadata.
seo/meta-tags-optimizer/SKILL.md - Schema Generator · Produces JSON-LD structured data and validation guidance.
seo/schema-markup-generator/SKILL.md - Search Console · Primary SEO data source for site, query, and page performance.
- CMS Backends · Contentful, Ghost, Strapi, and WordPress endpoints used by SEO workflows.
Google Ads
Ads audit, management, and copy skills.
- Ads Audit · Audits account health and creates reusable business context.
google-ads/ads-audit/SKILL.md - Ads Manager · Manages campaigns, keywords, bids, negatives, and ads.
google-ads/ads/SKILL.md - Ads Copy · Generates RSA ad copy and A/B test variants.
google-ads/ads-copy/SKILL.md - Ads MCP Config · Service boundary for the external AdsAgent / MCP integration.
google-ads/ads/mcporter.json - AdsAgent · External Google Ads execution and read layer used by Ads workflows.
Quality
Tests, fixtures, and validation helpers.
- Tests · Unit, end-to-end, and LLM evaluation coverage for skill behavior.
test - GSC Fixture · Mock Search Console data used by analyzer and routing tests.
test/fixtures/sample_gsc_data.json
Connections 25
- SEO Analysis → GSC Analyze: runs
- SEO Analysis → CMS Detect: detects
- SEO Analysis → Preflight: preflights
- SEO Analysis → URL Inspection: inspects
- SEO Analysis → GSC Setup: guided by
- GSC Analyze → Search Console: reads
- CMS Detect → CMS Adapters: selects
- Preflight → CMS Adapters: checks
- CMS Adapters → CMS Backends: connects
- SEO Analysis → Content Writer: feeds findings
- Keyword Research → Content Writer: prioritizes topics
- Meta Optimizer → Content Writer: optimizes drafts
- Schema Generator → Content Writer: adds schema
- Ads Audit → Ads MCP Config: uses
- Ads MCP Config → AdsAgent: routes to
- Ads Audit → Ads Manager: shares context
- Ads Audit → Ads Copy: seeds copy
- Ads Audit → Keyword Research: borrows terms
- Setup → Agent Hosts: installs to
- Setup → Config Tool: uses
- Setup → Update Check: uses
- Upgrade Skill → Setup: maintains
- Tests → SEO Analysis: covers
- Tests → Ads Audit: covers
- Tests → GSC Fixture: mocks