Indie Artist Brand Development Agent Skill

SKILL.md — Skill 236: indie-artist-brand-development

> Skill Registry Documentation — the canonical reference for how skills are > registered, resolved, executed, and validated in this project. Read this > before adding or modifying a skill. Backed by the production agent framework > in tools/agent/.

1. Overview

This project ships a modular skill-registry agent framework that orchestrates evidence-backed Independent Artist Branding & Creative Marketing analysis. Skills are declared as markdown files (skills/*.md) with YAML frontmatter, augmented by a registry manifest (skills/registry.yaml), and executed by a hook-wrapped, schema-validated runtime. The same pipeline runs deterministically in CI (dry-run) and live with an LLM.

config/system.yaml  ──►  AgentConfig (frozen, env-overridable)
skills/*.md + skills/registry.yaml  ──►  SkillSpec[] (schema-validated)
config/schema/*.json  ──►  input/output JSON Schemas
references/*.md  ──►  RAG grounding (assets/reference-index.json)

2. Skill Lifecycle (register → resolve → execute → validate)

2.1 Registration

SkillRegistry.load() auto-discovers every skills/*.md file, parses its YAML frontmatter (name, description), and merges metadata from skills/registry.yaml:

| Field | Source | Purpose | |-------|--------|---------| | name, description | markdown frontmatter | identity | | step | registry.yaml | 1-based pipeline position (0 = not in pipeline) | | aliases | registry.yaml | alternate names the registry resolves | | input_schema / output_schema | registry.yaml → config/schema/*.json | JSON Schema contracts | | depends_on | registry.yaml | skills that must run before this one | | gates | registry.yaml | quality gates this skill contributes to | | enabled | registry.yaml | toggle without deleting the file |

Handlers are attached at runtime via registry.register_handler(name, fn).

2.2 Resolution

registry.resolve(key) resolves by name or alias. Raises SkillNotFoundError if absent. registry.pipeline() returns skills ordered by step (the default execution order).

2.3 Execution

registry.execute(key, args, state, hooks, tools) runs a skill through the full lifecycle:

1. PRE_EXECUTE hooks — observe/mutate inputs.
2. Input validation — args checked against input_schema.
3. Handler invocation — the Python handler runs (or the LLM in live mode).
4. Output validation — result checked against output_schema.
5. POST_EXECUTE hooks — observe/mutate outputs.
6. ON_DEGRADE hooks — if degradation escalated, emit limitation notices.
7. ON_ERROR hooks — if the skill raised, transform into a degraded result.
8. State recording — a StepRecord is appended to ExecutionState.

Failures never crash the run: a skill error becomes a degraded/failed SkillResult with an explicit degradation_level, and execution continues.

2.4 Validation

Both input and output are validated against their declared JSON Schemas (config/schema/*.json) using the dependency-free validator in tools/agent/tools.py. A schema violation raises SkillValidationError, which the executor converts into a degraded result + limitation notice.

3. Skill Catalog

| Step | Skill | Aliases | Gates | Input Schema | Output Schema | |------|-------|---------|-------|--------------|---------------| | 1 | sub-gather-requirements | intake, requirements | U4, U5 | requirementsin.json | requirementsout.json | | 2 | sub-evidence-collector | evidence, data-librarian | U1, U3, U6 | evidencein.json | evidenceout.json | | 3 | sub-core-analysis | analysis, core-analysis | G1–G4, U6 | coreanalysisin.json | coreanalysisout.json | | 4 | sub-knowledge-updater | knowledge, research-librarian | U1, U3 | knowledgein.json | knowledgeout.json | | 5 | sub-advisor | advisor, synthesis | U2, U5, U6 | advisorin.json | advisorout.json |

main.md (indie-artist-brand-development) is the harness entry point (step 0); it documents the human-readable protocol. The runtime pipeline is the five sub-skills above, executed in step order.

4. Input/Output JSON Schemas

All schemas live in config/schema/ as JSON Schema (draft-07). Each skill has a _in.json and _out.json. Example (requirements_out.json):

{
  "type": "object",
  "properties": {
    "object": {"type": "string"},
    "scope": {"type": "string"},
    "timeframe": {"type": "string"},
    "language": {"type": "string", "enum": ["en", "vi"]},
    "analysis_type": {"type": "string",
      "enum": ["combined","identity","audience","distribution","ip_revenue","career"]}
  },
  "required": ["object","scope","timeframe","language","analysis_type"],
  "additionalProperties": false
}

Schemas are validated by tools/agent/tools.py::validate() (supports the subset: type, properties, required, items, enum, minimum/maximum, minLength/maxLength, additionalProperties:false).

5. Hooks

Lifecycle hooks (tools/agent/hooks.py) decouple cross-cutting concerns from skill logic. Four built-in hooks ship enabled by default:

| Hook | Phases | Purpose | |------|--------|---------| | logging | all | emit a structured log event per phase | | state_sync | all | append lifecycle events to ExecutionState.events | | event_emission | ONDEGRADE | surface degradation as limitation notices | | gate_enforcement | ONGATE | audit-trail failed gates after retries |

Register a custom hook:

from tools.agent import HookManager, Hook, HookPhase
mgr.register_fn("my_hook", [HookPhase.POST_EXECUTE], my_fn, priority=50)

A raising hook is captured (never crashes the run) and recorded as a limitation.

6. Tools

Tools (tools/agent/tools.py) are dynamically invokable capabilities with input/output JSON Schemas and Python execution handlers. Built-in tools:

| Tool | Aliases | Purpose | |------|---------|---------| | read_file | Read | read a workspace file | | write_file | Write | write text to a workspace file | | run_bash | Bash | bounded-timeout shell command | | web_search | WebSearch | best-effort web search (Tier 4) | | web_fetch | WebFetch | fetch a URL to text | | knowledge_query | — | query SECOND-KNOWLEDGE-BRAIN.md (tiered citations) | | append_knowledge | — | append scored, deduped entries to the brain | | skill_invoke | Skill | record an intent to invoke another skill |

Inputs are validated before execution; outputs after. Network tools degrade gracefully when requests is absent. Manifest: ToolRegistry.to_manifest().

7. Router

The chain-of-thought router (tools/agent/router.py) classifies a query into intents (keyword-weighted scoring), maps intents to skills, and emits a RouteDecision (pipeline, language, confidence, reasoning). When no intent clears min_confidence, it falls back to the full default pipeline so the harness is always safe. Language is detected from Vietnamese diacritics.

8. Context Window & Token Budgeting

ContextManager (tools/agent/context.py) tracks typed context entries (system, skill, step, evidence, tool, user), estimates their token cost with a dependency-free heuristic, and prunes/compresses when the running total exceeds max_tokens - reserve_tokens. Pinned entries (system, user) are never pruned; older steps are compressible to a fraction of their tokens. A pinned-only overflow raises ContextError.

9. Configuration

config/system.yaml + INDIE_AGENT_* env vars → frozen AgentConfig (tools/agent/config.py). Precedence: defaults .md with name + description` frontmatter and the standard sections (Role & Persona, Workflow, Tools, Output Format, Quality Gates).

1. Add an entry to skills/registry.yaml with step, aliases,

input_schema, output_schema, depends_on, gates.

1. Author the JSON Schemas in config/schema/_in.json and

_out.json.

1. Register a Python handler via registry.register_handler("sub-", fn)

(the handler signature is (args, state, tools) -> SkillResult).

1. Add a prompt template in references/prompt-templates/.md for live

LLM grounding.

1. Add tests under tests/ and re-run python tools/validate_project.py.

12. Programmatic API

from tools.agent import (
    SkillRegistry, HookManager, ToolRegistry, Router, ContextManager,
    DryRunClient, load_config, setup_logging, ExecutionState,
)
from tools.agent.hooks import install_builtin_hooks

cfg = load_config()
log = setup_logging(cfg.log_level, cfg.log_json)
registry = SkillRegistry(); registry.load()
tools = ToolRegistry(); tools = __import__("tools.agent.tools", fromlist=["build_default_tools"]).build_default_tools()
hooks = HookManager()
state = ExecutionState(query="...", mode="dry-run")
install_builtin_hooks(hooks, state, log_fn=log.debug,
                      enable_logging=cfg.feature_flags.logging_hook, ...)
for spec in registry.pipeline():
    registry.execute(spec.name, {...}, state, hooks, tools)

13. References

• PROJECT-detail.md — full technical specification
• assets/architecture.md — system diagram
• assets/skill-graph.json — skill dependency graph (generated)
• references/domain-knowledge.md — curated domain reference cards
• references/source-registry.md — tiered authoritative source map
• SECOND-KNOWLEDGE-BRAIN.md — living, auto-crawled knowledge base
• tools/agent/ — the framework source

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dungnotnull
• Source: dungnotnull/indie-artist-brand-development-agent-skill
• License: MIT

Install and usage instructions live in the source repository linked above.